archive/bramw_baserow
1
0
Fork 0
mirror of https://gitlab.com/bramw/baserow.git synced 2025-04-07 14:25:37 +00:00
Code Issues Projects Releases Wiki Activity

Add docker upgrade docs

Browse source
This commit is contained in:
Nigel Gott 2022-05-10 15:44:28 +00:00
parent d33b6b83df
commit 68d30b690d
4 changed files with 157 additions and 76 deletions

4
deploy/all-in-one/docker-compose.yml
View file

@ -6,6 +6,10 @@ services:
build:
dockerfile: $PWD/deploy/all-in-one/Dockerfile
context: $PWD
environment:
EMAIL_SMTP: 'yes'
EMAIL_SMTP_HOST: 'mailhog'
EMAIL_SMTP_PORT: '1025'
ports:
- "80:80"
- "443:443"

2
docs/development/running-the-dev-environment.md
View file

@ -35,7 +35,7 @@ https://www.linode.com/docs/development/version-control/how-to-install-git-on-li
Once you have finished installing all the required software you should be able to run
the following commands in your terminal.
```
```bash
$ docker -v
Docker version 20.10.6, build 370c289
$ docker-compose -v

113
docs/installation/install-with-docker-compose.md
View file

@ -1,6 +1,6 @@
# Install with Docker compose
> Any questions, problems or suggestions with this guide? Ask a question in our
> Any questions, problems or suggestions with this guide? Ask a question in our
> [community](https://community.baserow.io/) or contribute the change yourself at
> https://gitlab.com/bramw/baserow/-/tree/develop/docs .
@ -10,7 +10,7 @@ If you haven't already installed docker and docker-compose on your computer you
so by following the instructions on https://docs.docker.com/desktop/ and
https://docs.docker.com/compose/install/.
> Docker-compose version 3.4 and Docker version 19.03 are the minimum versions
> Docker-compose version 3.4 and Docker version 19.03 are the minimum versions
> required by our provided files.
If you want to get the docker-compose.yml via git then you can install it by following
@ -20,7 +20,7 @@ https://www.linode.com/docs/development/version-control/how-to-install-git-on-li
After installing all the required software you should be able to run the following
commands in your terminal.
```
```bash
$ docker -v
Docker version 20.10.12, build e91ed57
$ docker-compose -v
@ -32,18 +32,21 @@ git version 2.25.1
If all commands return something similar as described in the example, then you are ready
to proceed!
## Downloading the Baserow example docker-compose.yml
## Downloading the Baserow example docker-compose.yml
You can download the example Baserow `docker-compose.yml` by either directly downloading
the file from
the file from
[https://gitlab.com/bramw/baserow/-/blob/master/docker-compose.yml](https://gitlab.com/bramw/baserow/-/blob/master/docker-compose.yml)
and running:
```bash
curl -o docker-compose.yml https://gitlab.com/bramw/baserow/-/raw/master/docker-compose.yml
curl -o Caddyfile https://gitlab.com/bramw/baserow/-/raw/master/Caddyfile
docker-compose up -d
```
or by directly cloning our git repo so you can get updates easier:
```bash
$ cd ~/baserow
$ git clone --depth=1 --branch master https://gitlab.com/bramw/baserow.git
@ -69,10 +72,11 @@ docker-compose up -d
## Usage
To use this docker-compose.yml to run Baserow you must set the three required
environment variables in the `x-backend-required-variables` section inside the
`docker-compose.yml` and review the variables in the `x-common-important-variables`
section. If you receive the following error it is because you need to set the required
environment variables in the `x-backend-required-variables` section inside the
`docker-compose.yml` and review the variables in the `x-common-important-variables`
section. If you receive the following error it is because you need to set the required
environment variables first:
```
ERROR: Missing mandatory value for "environment" option interpolating
```
@ -80,65 +84,88 @@ ERROR: Missing mandatory value for "environment" option interpolating
If you are upgrading from Baserow 1.8.2 or earlier please read the additional section
below.
See [Configuring Baserow](configuration.md) for information on the
other environment variables you can configure.
See [Configuring Baserow](configuration.md) for information on the other environment
variables you can configure.
## How to set environment variables
You can set these variables by using docker-compose env file
(https://docs.docker.com/compose/environment-variables/#the-env-file):
1. Copy the `.env.example` file found in the root of Baserows repository
1. Copy the `.env.example` file found in the root of Baserows repository
(https://gitlab.com/bramw/baserow/-/blob/master/.env.example) to `.env`:
```
curl -o .env https://gitlab.com/bramw/baserow/-/raw/master/.env.example
```
2. Edit `.env` and provide values for the missing environment variables.
3. `docker-compose up`
Alternatively you can set these variables by either running docker-compose with
the environment variables set on the command line (fill in secure values first):
Alternatively you can set these variables by either running docker-compose with the
environment variables set on the command line (fill in secure values first):
```
SECRET_KEY= DATABASE_PASSWORD= REDIS_PASSWORD= docker-compose up
```
## Upgrading from Baserow version 1.9.0 or later
1. It is recommended that you backup your data before upgrading, see the Backup sections
below for more details on how to do this.
2. Stop your existing Baserow install when safe to do so:
`docker-compose down`
3. Get the latest Baserow version by running:
`git pull`
4. Startup the new version of Baserow by running: `docker-compose up -d`
5. Monitor the logs using: `docker-compose logs -f`
6. Once you see the following log line your Baserow upgraded and is now available again:
```
[BASEROW-WATCHER][2022-05-10 08:44:46] Baserow is now available at ...
```
## Upgrading from Baserow 1.8.2's docker-compose file
> If you were previously using a separate api.your_baserow_server.com domain this is no
> longer needed. Baserow will now work on a single domain accessing the api at
> YOUR_DOMAIN.com/api.
To upgrade from 1.8.2's docker-compose file from inside the Baserow git repo you need to:
To upgrade from 1.8.2's docker-compose file from inside the Baserow git repo you need
to:
1. Stop your existing Baserow install when safe to do so:
`docker-compose down`
2. `git pull`
3. Copy `.env.example` to `.env` and edit `.env` filling in the missing variables
below:
- `SECRET_KEY` to a secure value, existing logins sessions will be invalidated.
- `DATABASE_PASSWORD` to a secure password (this defaulted to 'baserow' before, in
step 3 we are going to change the database users password to the value you set)
- `REDIS_PASSWORD` to a secure password.
- `WEB_FRONTEND_PORT` back to 3000 if you want to continue accessing Baserow on
that port (it now defaults to 80).
- `BASEROW_PUBLIC_URL` to the URL/IP/Domain you were using access Baserow remotely
(it must begin with http:// or https://). If you have set `WEB_FRONTEND_PORT` to
anything but 80 you must append it to the end of `BASEROW_PUBLIC_URL`.
- `BASEROW_CADDY_ADDRESSES` configures which addresses the new internal Caddy reverse
proxy listens on. By default, it will serve http only, enable automatic https
by setting to `https://YOUR_DOMAIN_NAME.com`. Append `,http://localhost` if you
still want to be able to access Baserow from `localhost`.
4. Run the command below which will change the baserow postgresql users password to
what you have set in step 1 in the .env file (no need to edit the command):
2. `git pull`
3. Copy `.env.example` to `.env` and edit `.env` filling in the missing variables below:
- `SECRET_KEY` to a secure value, existing logins sessions will be invalidated.
- `DATABASE_PASSWORD` to a secure password (this defaulted to 'baserow' before, in
step 3 we are going to change the database users password to the value you set)
- `REDIS_PASSWORD` to a secure password.
- `WEB_FRONTEND_PORT` back to 3000 if you want to continue accessing Baserow on that
port (it now defaults to 80).
- `BASEROW_PUBLIC_URL` to the URL/IP/Domain you were using access Baserow remotely
(it must begin with http:// or https://). If you have set `WEB_FRONTEND_PORT` to
anything but 80 you must append it to the end of `BASEROW_PUBLIC_URL`.
- `BASEROW_CADDY_ADDRESSES` configures which addresses the new internal Caddy
reverse proxy listens on. By default, it will serve http only, enable automatic
https by setting to `https://YOUR_DOMAIN_NAME.com`. Append `,http://localhost` if
you still want to be able to access Baserow from `localhost`.
4. Run the command below which will change the baserow postgresql users password to what
you have set in step 1 in the .env file (no need to edit the command):
```
docker-compose run --rm backend bash -c "PGPASSWORD=baserow psql -h db -U baserow -c \"ALTER USER baserow WITH PASSWORD '$DATABASE_PASSWORD';\" && echo 'Successfully changed Baserow's db user password'"
```
5. `docker-compose up -d`
5. `docker-compose up -d`
## How To
### Running management commands
You can see and run the Baserow backend management commands like so:
```bash
docker-compose exec backend /baserow/backend/docker/docker-entrypoint.sh help
```
@ -152,9 +179,9 @@ $ docker-compose logs
### Run Baserow alongside existing services
Baserow's docker-compose files will automatically expose the `caddy` service on your
network on ports 80 and 433 by default. If you already have applications or
services using those ports the Baserow service which uses that port will crash. To fix
this you can set the `WEB_FRONTEND_PORT` variable to change the default of port 80 and
network on ports 80 and 433 by default. If you already have applications or services
using those ports the Baserow service which uses that port will crash. To fix this you
can set the `WEB_FRONTEND_PORT` variable to change the default of port 80 and
`WEB_FRONTEND_SSL_PORT` to change the default port of 443.
```bash
@ -168,7 +195,7 @@ following command to make Baserow available at the domain with
[automatic https](https://caddyserver.com/docs/automatic-https#overview) provided by
Caddy.
> Append `,http://localhost` to BASEROW_CADDY_ADDRESSES if you still want to be able to
> Append `,http://localhost` to BASEROW_CADDY_ADDRESSES if you still want to be able to
> access your server from the machine it is running on using http://localhost. See
> [Caddy's Address Docs](https://caddyserver.com/docs/caddyfile/concepts#addresses)
> for all supported values for BASEROW_CADDY_ADDRESSES.
@ -204,7 +231,7 @@ variable to `false` (or any value which is not `true`) like so:
MIGRATE_ON_STARTUP=false docker-compose up -d
```
### Run a one off migration
### Run a one off migration
```bash
# Use run if you have stopped your docker-compose environment
@ -226,8 +253,8 @@ SYNC_TEMPLATES_ON_STARTUP=false docker-compose up -d
### Back-up your Baserow DB
1. Please read the output of `docker-compose run backend manage backup_baserow --help`.
2. Please ensure you only back-up a Baserow database which is not actively being used
by a running Baserow instance or any other process which is making changes to the
2. Please ensure you only back-up a Baserow database which is not actively being used by
a running Baserow instance or any other process which is making changes to the
database.
```bash
@ -242,9 +269,9 @@ docker-compose run -v ~/baserow_backups:/baserow/backups backend backup -f /base
### Restore your Baserow DB from a back-up
1. Please read the output of `docker-compose run backend manage restore_baserow --help`
1. Please ensure you never restore Baserow using a pooled connection but instead do
the restoration via direct database connection.
1. Please read the output of `docker-compose run backend manage restore_baserow --help`
1. Please ensure you never restore Baserow using a pooled connection but instead do the
restoration via direct database connection.
1. Make a new, empty database to restore the back-up file into, please do not overwrite
existing databases as this might cause database inconsistency errors.

114
docs/installation/install-with-docker.md
View file

@ -8,9 +8,9 @@
> advised however that you install the latest version of Docker available.
> Please check that your docker is up-to date by running `docker -v`.
This guide assumes you already have Docker installed and have permissions to run Docker
containers. See the [Install on Ubuntu](install-on-ubuntu.md) for a installation from
scratch instead.
This guide assumes you already have Docker installed and have permissions to run Docker
containers. See the [Install on Ubuntu](install-on-ubuntu.md) for an installation from
scratch.
## Quick Start
@ -33,18 +33,19 @@ docker run \
* Change `BASEROW_PUBLIC_URL` to `https://YOUR_DOMAIN` or `http://YOUR_IP` to enable
external access.
* Add `-e BASEROW_CADDY_ADDRESSES=https://YOUR_DOMAIN` to enable
[automatic Caddy HTTPS](https://caddyserver.com/docs/caddyfile/automatic-https#overview).
[automatic Caddy HTTPS](https://caddyserver.com/docs/caddyfile/automatic-https#overview)
.
* Optionally add `-e DATABASE_URL=postgresql://user:pwd@host:port/db` to use an external
Postgresql.
* Optionally add `-e REDIS_URL=redis://user:pwd@host:port` to use an external Redis.
> 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 container publicly from your machine on its network. If this
> and expose the above container publicly from your machine on its network. If this
> is not intended then run with the following ports instead:
> `-p 127.0.0.1:80:80 -p 127.0.0.1:443:443` which makes your Baserow only accessible
> from the machine it is running on.
> Please see https://github.com/chaifeng/ufw-docker for more information and how to
> Please see https://github.com/chaifeng/ufw-docker for more information and how to
> setup ufw to work securely with docker.
## Image Feature Overview
@ -65,7 +66,57 @@ single container for ease of use. A quick summary of its features are:
* Provides a CLI for execing admin commands against a running Baserow container or
running one off commands against just a Baserow data volume.
## Example Commands
## Upgrading from a previous version
1. It is recommended that you backup your data before upgrading, see the Backup sections
below for more details on how to do this.
2. Stop your existing Baserow container:
```bash
docker stop baserow
```
3. Bump the image version in the `docker run` command you usually use to run your
Baserow and start up a brand-new container:
```bash
# We haven't yet deleted the old Baserow container so you need to start this new one
# with a different name to prevent an error like:
# `response from daemon: Conflict. The container name "/baserow" is already in use by
# container`
docker run \
-d \
--name baserow_version_REPLACE_WITH_NEW_VERSION \
# YOUR STANDARD ARGS HERE
baserow/baserow:REPLACE_WITH_LATEST_VERSION
```
5. Baserow will automatically upgrade itself on startup, follow the logs to monitor it:
```bash
docker logs -f baserow_version_REPLACE_WITH_NEW_VERSION
```
6. Once you see the following log line your Baserow upgraded and is now available again:
```
[BASEROW-WATCHER][2022-05-10 08:44:46] Baserow is now available at ...
```
7. Make sure your Baserow has been successfully upgraded by visiting it and checking
everything is working as expected and your data is still present.
8. If everything works you can now remove the old Baserow container.
> WARNING: If you have not been using a volume to persist the `/baserow/data` folder
> inside the container this will delete all of your Baserow data stored in this
> container permanently.
```bash
docker rm baserow
```
# Example Commands
See [Configuring Baserow](configuration.md) for more detailed information on all the
other environment variables you can configure.
@ -181,23 +232,24 @@ docker run \
### With a Postgresql server running on the same host as the Baserow docker container
This is assuming you are using the postgresql server bundled by ubuntu. If not then
you will have to find the correct locations for the config files for your OS.
This is assuming you are using the postgresql server bundled by ubuntu. If not then you
will have to find the correct locations for the config files for your OS.
1. Find out what version of postgresql is installed by running
`sudo ls /etc/postgresql/`
`sudo ls /etc/postgresql/`
2. Open `/etc/postgresql/YOUR_PSQL_VERSION/main/postgresql.conf` for editing as root
3. Find the commented out `# listen_addresses` line.
4. Change it to be:
`listen_addresses = '*' # what IP address(es) to listen on;`
`listen_addresses = '*' # what IP address(es) to listen on;`
5. Open `/etc/postgresql/YOUR_PSQL_VERSION/main/pg_hba.conf` for editing as root
6. Add the following line to the end which will allow docker containers to connect.
`host all all 172.17.0.0/16 md5`
`host all all 172.17.0.0/16 md5`
7. Restart postgres to load in the config changes.
`sudo systemctl restart postgresql`
`sudo systemctl restart postgresql`
8. Check the logs do not have errors by running
`sudo less /var/log/postgresql/postgresql-YOUR_PSQL_VERSION-main.log`
`sudo less /var/log/postgresql/postgresql-YOUR_PSQL_VERSION-main.log`
9. Run Baserow like so:
```bash
docker run \
-d \
@ -216,10 +268,10 @@ docker run \
baserow/baserow:1.10.0
```
### Supply secrets using files
### Supply secrets using files
The `DATABASE_PASSWORD`, `SECRET_KEY` and `REDIS_PASSWORD` environment variables
can instead be loaded using a file by using the `*_FILE` variants:
The `DATABASE_PASSWORD`, `SECRET_KEY` and `REDIS_PASSWORD` environment variables can
instead be loaded using a file by using the `*_FILE` variants:
```bash
echo "your_redis_password" > .your_redis_password
@ -242,7 +294,7 @@ docker run \
baserow/baserow:1.10.0
```
### Start just the embedded database
### Start just the embedded database
If you want to directly access the embedded Postgresql database then you can run:
@ -260,9 +312,9 @@ docker exec -it baserow cat /baserow/data/.pgpass
# the password above with the username `baserow`.
```
### Run a one off command on the database
### Run a one off command on the database
If you want to run a one off backend command against your Baserow data volume without
If you want to run a one off backend command against your Baserow data volume without
starting Baserow normally you can do so with the `backend-cmd-with-db` argument like so:
```bash
@ -277,10 +329,10 @@ docker run -it \
## Backing up and Restoring Baserow
Baserow stores all of its persistent data in the `/baserow/data` directory by default.
We strongly recommend you mount a docker volume into this location to persist
Baserows data so you do not lose it if you accidentally delete your Baserow container.
We strongly recommend you mount a docker volume into this location to persist Baserows
data so you do not lose it if you accidentally delete your Baserow container.
> The backup and restore operations discussed below are best done on a Baserow server
> The backup and restore operations discussed below are best done on a Baserow server
> which is not being used.
### Backup all of Baserow
@ -318,9 +370,8 @@ docker run --rm -v new_baserow_data_volume $PWD:/backup ubuntu bash -c "mkdir -p
### Backup only Baserow's Postgres database
Please ensure you only back-up a Baserow database which is not actively being used
by a running Baserow instance or any other process which is making changes to the
database.
Please ensure you only back-up a Baserow database which is not actively being used by a
running Baserow instance or any other process which is making changes to the database.
Baserow stores all of its own data in Postgres. To backup just this database you can run
the command below.
@ -359,9 +410,9 @@ docker run -it --rm \
## Running healthchecks on Baserow
The Dockerfile already defines a HEALTHCHECK command which will be used by software
that supports it. However if you wish to trigger a healthcheck yourself on a running
Baserow container then you can run:
The Dockerfile already defines a HEALTHCHECK command which will be used by software that
supports it. However if you wish to trigger a healthcheck yourself on a running Baserow
container then you can run:
```bash
docker exec baserow ./baserow.sh backend-cmd backend-healthcheck
@ -408,9 +459,8 @@ docker run \
baserow/baserow:1.10.0
```
Or you can just store it directly in the volume at `baserow_data/env` meaning it will
be loaded whenever you mount in this data volume.
Or you can just store it directly in the volume at `baserow_data/env` meaning it will be
loaded whenever you mount in this data volume.
### Building your own image from Baserow