Local development setup ‐ Debian 12

This document is being written on a Debian 12 desktop, so the instructions may need some adjustment on other distributions.

The asdf runtime version manager is used for installing Python and NodeJS.

Set up the prerequisites

Install required Debian packages

$ sudo apt -y install --no-install-recommends build-essential curl default-libmysqlclient-dev freetds-dev libffi-dev libpq-dev \
  libsasl2-dev libsasl2-modules-gssapi-mit libssl-dev python3-dev pwgen unixodbc-dev xmlsec1 xvfb

Install asdf

$ cat <<EOF >> ~/.bashrc
. "\$HOME/.asdf/asdf.sh"
. "\$HOME/.asdf/completions/asdf.bash"
EOF

Then restart the terminal session

Install Docker

# Add Docker's official GPG key:
$ sudo apt update && sudo apt -y install ca-certificates curl
$ sudo install -m 0755 -d /etc/apt/keyrings
$ sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
$ sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
$ echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
$ sudo apt update

# Install Docker Engine CE packages
$ sudo apt -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify docker works

$ sudo docker run hello-world

Add your user to the "docker" group

$ sudo usermod -aG docker $USER

Then logout of your desktop and login again, so the group membership change becomes effective.

Otherwise you'll receive docker errors further down the page when you try to build the docker image.

Clone the Redash source code

$ git clone https://github.com/getredash/redash
$ cd redash

Install and set the version of Python to use

$ asdf plugin add python
$ asdf install python 3.10.14
$ asdf local python 3.10.14

Create a Python virtual environment

This ensures any Python libraries we install only affect the virtual environment, not the whole system:

$ python3 -m venv ~/redashvenv1
$ source ~/redashvenv1/bin/activate

Note

When the Python virtual environment is active in your session, it changes the prompt to look like this:

(redashvenv1) $

Install Redash's Python dependencies into the virtual environment:

(redashvenv1) $ pip3 install wheel  # "wheel" needs to be installed by itself first
(redashvenv1) $ pip3 install --upgrade black ruff launchpadlib pip setuptools
(redashvenv1) $ pip3 install poetry && poetry install --only main,all_ds,dev

Configure Pre-commit

Before committing changes to GitHub or creating a pull request, the source code needs to be checked and formatted to meet our quality standards:

(redashvenv1) $ make format
pre-commit run --all-files
isort....................................................................Passed
black....................................................................Passed
flake8...................................................................Passed

Enable the automatic Pre-commit check before commit:

(redashvenv1) $ pre-commit install

Install and set the version of NodeJS to use

$ asdf plugin add nodejs
$ asdf install nodejs 18.20.4
$ asdf local nodejs 18.20.4

Install Yarn 1.x

$ npm install -g [email protected]

Install the NodeJS dependencies

$ yarn

Compile and build

Redash uses GNU Make to run things, so if you're not sure about something it's often a good idea to take a look over the Makefile which can help. 😄

Build the Redash front end

$ make build

Build local Redash Docker image

$ make compose_build

On my desktop (Ryzen 5600X) that took about 12 minutes to complete the first time. After that though, it's much faster at about a minute and a half each time.

It's a good idea to check that the docker images were built ok. We do that by telling docker to show us the local "docker images", which should include these three new ones. It's important the "created" time shows them to be very recent... if it's not, then they're old images left over from something else. 😉

$ docker image list
REPOSITORY         TAG       IMAGE ID       CREATED         SIZE
redash_scheduler   latest    85bc2dc57801   2 minutes ago   1.38GB
redash_server      latest    85bc2dc57801   2 minutes ago   1.38GB
redash_worker      latest    85bc2dc57801   2 minutes ago   1.38GB

Start Redash locally, using the docker images you just built

$ make create_database
$ make up

The docker compose ps command should show all of the docker pieces are running:

$ docker compose ps
       Name                     Command                  State                                  Ports                            
---------------------------------------------------------------------------------------------------------------------------------
redash_email_1       bin/maildev                      Up (healthy)   1025/tcp, 1080/tcp, 0.0.0.0:1080->80/tcp,:::1080->80/tcp    
redash_postgres_1    docker-entrypoint.sh postg ...   Up             0.0.0.0:15432->5432/tcp,:::15432->5432/tcp                  
redash_redis_1       docker-entrypoint.sh redis ...   Up             6379/tcp                                                    
redash_scheduler_1   /app/bin/docker-entrypoint ...   Up             5000/tcp                                                    
redash_server_1      /app/bin/docker-entrypoint ...   Up             0.0.0.0:5001->5000/tcp,:::5001->5000/tcp,                   
                                                                     0.0.0.0:5678->5678/tcp,:::5678->5678/tcp                    
redash_worker_1      /app/bin/docker-entrypoint ...   Up             5000/tcp

The Redash web interface should also be available at http://localhost:5001, ready to be configured:

Once you've finished confirming everything works the way you want, then shut down the containers with:

$ make down

Next step: Testing