If you want to contribute to Baserow you need to setup the development environment on
your local computer. The best way to do this is via
docker-compose so that you can
start the app with the least amount of hassle.
If you are familiar with git and docker-compose run these commands to launch baserow’s dev environment locally, otherwise please start from the Installing Requirements section below.
$ git clone --branch master https://gitlab.com/bramw/baserow.git $ cd baserow $ docker-compose -f docker-compose.yml -f docker-compose.dev.yml up $ # OR use our ./dev.sh script which also ensures your dev containers run as your user $ ./dev.sh --build
If you haven’t already installed docker and docker-compose on your computer you can do so by following the instructions on https://docs.docker.com/desktop/ and https://docs.docker.com/compose/install/.
Docker version 19.03 is the minimum required to build Baserow. It is strongly advised however that you install the latest version of Docker available: 20.10. Please check that your docker is up to date by running
You will also need git installed which you can do by following the instructions on https://www.linode.com/docs/development/version-control/how-to-install-git-on-linux-mac-and-windows/ .
Once you have finished installing all the required software you should be able to run the following commands in your terminal.
$ docker -v Docker version 20.10.6, build 370c289 $ docker-compose -v docker-compose version 1.26.2, build eefe0d31 $ git --version git version 2.24.3 (Apple Git-128)
If all commands return something similar as described in the example, then you are ready to proceed!
If you run into any issues starting your development environment feel free to contact us via the form on https://baserow.io/contact.
For example purposes I have created a directory in my home folder named
can of course follow the steps in any directory, but in this tutorial I will assume the
working directory is
First we have to clone the repository. Execute the following commands to clone the master branch. If you are not familiar with git clone, this will download a copy of Baserow’s code to your computer.
Note that if you have already started the running baserow locally guide once, you might need to rebuild the images for the development environment by using the command
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d --buildor just
./dev.sh build_onlybecause they have container name conflicts.
$ cd ~/baserow $ git clone --branch master https://gitlab.com/bramw/baserow.git Cloning into 'baserow'... ... $ cd baserow
Now that we have our copy of the repo and have changed directories to the newly
baserow, we can bring up the containers. You just have to execute the
docker-compose command using the
docker-compose.yml file. It might take a while for
the command to finish, this is because the images have to be built from scratch.
$ docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d $ # Or instead you can use ./dev.sh which also ensures the dev environment runs as you $ ./dev.sh $ # Run ./dev.sh for more details on what it can do! Building backend ... Starting db ... done Starting mjml ... done Starting redis ... done Starting backend ... done Starting web-frontend ... done
Your dev environment is now running, the database has been automatically migrated for you and the baserow templates have been synced. You can now visit http://localhost:3000 to sign up and login to your Baserow.
Baserow’s backend container exposes a rest API. Find the API spec for your local version of Baserow at http://localhost:8000/api/redoc/ . To check that it is working correctly when you visit http://localhost:8000/api/groups/ in a browser you should see the error “Authentication credentials were not provided.” as no JWT was provided.
The dev environment consists of a number of docker containers, see:
If you use
./dev.sh by default it will attempt to open tabs in your terminal and
attach to the running baserow containers. Otherwise you can do so manually by running
the following commands:
$ # Run the commands below to connect to the various different parts of Baserow $ docker attach backend $ docker attach celery $ docker attach web-frontend
When attached you can press CTRL-C to end the current containers main process. However unlike normal docker containers this one will not exit immediately but instead present you with a bash terminal. In this terminal you can then run any admin commands you wish or inspect the state of the containers. Simply press up and go through the containers bash history to get the original command to restart the containers main process.
See the docker how to guide for a larger collection of useful operations and commands, below is a quick example of some of the more common ones:
$ # View the logs $ docker-compose logs $ # Migrate $ ./dev.sh run backend manage migrate $ # Restart and Build $ ./dev.sh restart --build
Both the web-frontend and backend containers need to keep running while you are developing. They also monitor file changes and update automatically, so you don’t need to worry about reloading. Go and make some changes yourself. You should see the result right away.
For further reading on how to work with docker containers and django check out: