Docker

warning

The following guide is intended for contributors to set up ToolJet locally. If you're interested in self-hosting ToolJet, please refer to the Setup section.

Docker Compose is the easiest way to set up the ToolJet server and client locally.

If you just want to try out ToolJet locally with docker, you can follow the steps here.

Prerequisites

Make sure you have the latest version of docker and docker compose installed.

Official docker installation guide

Official docker-compose installation guide

Setting up

warning

If you are setting up on a Windows machine, we advise you to set up Docker Desktop with WSL2. More information is available here.

Make sure to run it within the WSL2 terminal.

1. Clone the repository:

git clone https://github.com/tooljet/tooljet.git

2. Create a .env file by copying .env.example. More information on the variables that can be set is given in the environment variables reference.

cp ./deploy/docker/.env.internal.example .env

3. Populate the keys in the .env using the below the command:

chmod +x ./deploy/docker/internal.sh && ./deploy/docker/internal.sh

warning

If you are setting up on a Windows machine, please ensure that the .env file line endings are set to LF, as they will be CRLF by default unless configured otherwise.

4. Build Docker images.

docker compose build
docker compose run --rm  plugins npm run build:plugins

5. Run ToolJet.

docker compose up

ToolJet should now be served locally at http://localhost:8082.

8. To shut down the containers, use the below commands:

docker compose stop

Making changes to the codebase

If you make any changes to the codebase or pull the latest changes from upstream, the ToolJet server container will hot reload the application without any action required from you.

Note:

1. If the changes include database migrations or new npm package additions in package.json, you need to restart the ToolJet server container by running docker compose restart server.

2. If you need to add a new binary or system library to the container itself, you would need to add those dependencies in docker/server.Dockerfile.dev and then rebuild the ToolJet server image. You can do that by running docker compose build server. After the build completes, you can start all services by running docker compose up.

Example: Let's say you need to install the imagemagick binary in your ToolJet server's container. You'd then need to make sure that apt installs imagemagick while building the image. The Dockerfile at docker/server.Dockerfile.dev for the server would then look something like this:

FROM node:18.18.2-buster AS builder

RUN apt update && apt install -y \
build-essential  \
postgresql \
freetds-dev \
imagemagick

RUN mkdir -p /app
WORKDIR /app

COPY ./server/package.json ./server/package-lock.json ./
RUN npm install

ENV NODE_ENV=development

COPY ./server/ ./

COPY ./docker/ ./docker/

COPY ./.env ../.env

RUN ["chmod", "755", "entrypoint.sh"]

Once you've updated the Dockerfile, rebuild the image by running docker compose build server. After building the new image, start the services by running docker compose up.

Running Tests

Test config picks up config from .env.test file at the root of the project.

1. Run the following command to create and migrate data for test db:

docker compose run --rm -e NODE_ENV=test server npm run db:create
docker compose run --rm -e NODE_ENV=test server npm run db:migrate

2. To run the unit tests:

docker compose run --rm server npm run --prefix server test

3. To run e2e tests:

docker compose run --rm server npm run --prefix server test:e2e

4. To run a specific unit test:

docker compose run --rm server npm --prefix server run test <path-to-file>

Troubleshooting

Please open a new issue at https://github.com/ToolJet/ToolJet/issues or join our Slack Community if you encounter any issues when trying to run ToolJet locally.