bramw_baserow/docs/guides/baserow-docker-how-to.md

Baserow Docker how to

Find below a list of FAQs and common operations when working with Baserow's docker environment.

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 docker -v.

See baserow's docker api for the full details on what commands and environment variables baserow's docker-compose and docker image's support.

How To

View the logs

$ docker-compose logs 

Run Baserow alongside existing services

Baserow's docker-compose files will automatically expose the backend, web-frontend and media containers to your machine's network. If you already have applications or services using those ports the Baserow service which uses that port will crash.

To fix this you can change which ports Baserow will use by setting the corresponding environment variable:

• For backend set BACKEND_PORT which defaults to 8000
• For web-frontend set WEB_FRONTEND_PORT which defaults to 3000
• For media set MEDIA_PORT which defaults to 4000

This is how to set these variables in bash:

$ BACKEND_PORT=8001 docker-compose up 
$ # or using dev.sh
$ BACKEND_PORT=8001 ./dev.sh

Make Baserow publicly accessible

By default when you run docker-compose up you can only access Baserow from the same machine by visiting localhost:3000 or 127.0.0.1:3000. If you are running the Baserow docker containers on a remote server which you want to access over a network or the public internet you need to set some environment variables to expose Baserow.

Please be warned that there is a security flaw with docker and the ufw firewall. By default docker when exposing ports on 0.0.0.0 will bypass any ufw firewall rules and expose the above containers publicly from your machine on the network. Please see https://github.com/chaifeng/ufw-docker for more information and how to setup ufw to work securely with docker.

You will need to set the following three environment variables to successfully expose Baserow on your network.

1. HOST_PUBLISH_IP=0.0.0.0 - This will configure docker-compose.yml to expose Baserow's containers on all IP addresses on the host machine, instead of just localhost. Warning: if you are using UFW please see the warning above.
2. PUBLIC_BACKEND_URL={REPLACE_WITH_YOUR_DOMAIN_NAME_OR_HOST_IP}:8000 - This will ensure that Baserow clients will be able to successfully connect to the backend, if you can visit Baserow at port 3000 but you are getting API errors please ensure this variable is set correctly.
3. PUBLIC_WEB_FRONTEND_URL={REPLACE_WITH_YOUR_DOMAIN_NAME_OR_HOST_IP}:3000 - The same variable as above but the URL for the web-frontend container instead.

For example you could run the command below after replacing REPLACE_ME with the IP address or domain name of the server where Baserow is running:

$ HOST_PUBLISH_IP=0.0.0.0 PUBLIC_BACKEND_URL=REPLACE_ME:8000 PUBLIC_WEB_FRONTEND_URL=REPLACE_ME:3000 docker-compose up 

Configure an external email server

See the introduction for the all the of email environment variables available to configure Baserow. For a simple example you can start up Baserow locally and have it connect to an external SMTP server like so:

EMAIL_SMTP_HOST=TODO EMAIL_SMTP_PORT=TODO EMAIL_SMTP=True docker-compose up

Change the container user

When running the dev env you can set the UID and GID environment variables when building and running Baserow to change the user id and group id for the following containers:

• backend
• celery
• web-frontend

Remember you need to re-build if you change these variables or run ./dev.sh from a new user. This is because Baserow's images build with file permissions set to the given UID and GID, so if they change without a re-build they will be incorrect.

When using ./dev.sh it will automatically set UID and GID to the ids of the user running the command for you.

Disable automatic migration

You can disable automatic migration by setting the MIGRATE_ON_STARTUP environment variable to false (or any value which is not true) like so:

$ MIGRATE_ON_STARTUP=false docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
$ # Or instead using ./dev.sh 
$ ./dev.sh dont_migrate  # dev.sh supports this as an explicit argument.
$ MIGRATE_ON_STARTUP=false ./dev.sh # or dev.sh will pass through whatever you have set. 

Run a one off migration

# Run a one off dev container using the backend image which supports the "manage" command like so:
$ docker-compose -f docker-compose.yml -f docker-compose.dev.yml run backend manage migrate
$ # Or instead using ./dev.sh 
$ ./dev.sh run backend manage migrate

Disable automatic template syncing

You can disable automatic baserow template syncing by setting the SYNC_TEMPLATES_ON_STARTUP environment variable to false (or any value which is not true) like so:

$ SYNC_TEMPLATES_ON_STARTUP=false docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
$ # Or instead using ./dev.sh 
$ ./dev.sh dont_sync # dev.sh supports this as an explicit argument.
$ SYNC_TEMPLATES_ON_STARTUP=false ./dev.sh # or dev.sh it will pass through whatever you have set. 

Run a one off management command

# Run a one off dev container using the backend image which supports the "manage" command like so:
$ docker-compose -f docker-compose.yml -f docker-compose.dev.yml run backend manage sync_templates 
$ # Or instead using ./dev.sh 
$ ./dev.sh run backend manage sync_templates 

Common Problems

Build Error - Service 'backend' failed to build: unable to convert uid/gid chown

This error occurs when attempting to build Baserow's docker images with a version of Docker earlier than 19.03. It can also occur when you are attempting to build Baserow version 1.3 or earlier using a version of Docker less than 20.10. You can check your local docker version by running docker -v and fix the error by installing the latest version of Docker from https://docs.docker.com/get-docker/.

Permission denied errors

If you used Baserow's dev env prior to April 2021 with the provided docker files you might encounter permission errors in the containers when upgrading. With the old docker files build output could end up being owned by root. These root owned files if they still exist in your repo will cause a problem starting the new dev env as Baserow's containers now run as a non-root user.

To fix simply ensure all files in your baserow git repo are owned by your current user like so:

chown YOUR_USERNAME_HERE -R baserow/