Add docker upgrade docs

deploy/all-in-one/docker-compose.yml

@@ -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"

docs/development/running-the-dev-environment.md

@@ -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

docs/installation/install-with-docker-compose.md

@@ -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 
+environment variables in the `x-backend-required-variables` section inside the
-`docker-compose.yml` and review the variables in the `x-common-important-variables` 
+`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 
+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
+See [Configuring Baserow](configuration.md) for information on the other environment
-other environment variables you can configure.
+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
+Alternatively you can set these variables by either running docker-compose with the
-the environment variables set on the command line (fill in secure values first):
+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` 
+2. `git pull`
-3. Copy `.env.example` to `.env` and edit `.env` filling in the missing variables
+3. Copy `.env.example` to `.env` and edit `.env` filling in the missing variables below:
-   below:
+    - `SECRET_KEY` to a secure value, existing logins sessions will be invalidated.
-   - `SECRET_KEY` to a secure value, existing logins sessions will be invalidated.
+    - `DATABASE_PASSWORD` to a secure password (this defaulted to 'baserow' before, in
-   - `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)
-     step 3 we are going to change the database users password to the value you set)
+    - `REDIS_PASSWORD` to a secure password.
-   - `REDIS_PASSWORD` to a secure password.
+    - `WEB_FRONTEND_PORT` back to 3000 if you want to continue accessing Baserow on that
-   - `WEB_FRONTEND_PORT` back to 3000 if you want to continue accessing Baserow on
+      port (it now defaults to 80).
-     that port (it now defaults to 80).
+    - `BASEROW_PUBLIC_URL` to the URL/IP/Domain you were using access Baserow remotely
-   - `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
-     (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`.
-     anything but 80 you must append it to the end of `BASEROW_PUBLIC_URL`.
+    - `BASEROW_CADDY_ADDRESSES` configures which addresses the new internal Caddy
-   - `BASEROW_CADDY_ADDRESSES` configures which addresses the new internal Caddy reverse
+      reverse proxy listens on. By default, it will serve http only, enable automatic
-     proxy listens on. By default, it will serve http only, enable automatic https
+      https by setting to `https://YOUR_DOMAIN_NAME.com`. Append `,http://localhost` if
-     by setting to `https://YOUR_DOMAIN_NAME.com`. Append `,http://localhost` if you 
+      you still want to be able to access Baserow from `localhost`.
-     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
-4. Run the command below which will change the baserow postgresql users password to
+   you have set in step 1 in the .env file (no need to edit the command):
-   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
+network on ports 80 and 433 by default. If you already have applications or services
-services using those ports the Baserow service which uses that port will crash. To fix
+using those ports the Baserow service which uses that port will crash. To fix this you
-this you can set the `WEB_FRONTEND_PORT` variable to change the default of port 80 and
+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
+2. Please ensure you only back-up a Baserow database which is not actively being used by
-   by a running Baserow instance or any other process which is making changes to the
+   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 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
+1. Please ensure you never restore Baserow using a pooled connection but instead do the
-   the restoration via direct database connection.
+   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.
 

docs/installation/install-with-docker.md

@@ -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 
+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 
+containers. See the [Install on Ubuntu](install-on-ubuntu.md) for an installation from
-scratch instead.
+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
+This is assuming you are using the postgresql server bundled by ubuntu. If not then you
-you will have to find the correct locations for the config files for your OS.
+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
+The `DATABASE_PASSWORD`, `SECRET_KEY` and `REDIS_PASSWORD` environment variables can
-can instead be loaded using a file by using the `*_FILE` variants:
+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 
+We strongly recommend you mount a docker volume into this location to persist Baserows
-Baserows data so you do not lose it if you accidentally delete your Baserow container.
+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 
+Please ensure you only back-up a Baserow database which is not actively being used by a
-by a running Baserow instance or any other process which is making changes to the
+running Baserow instance or any other process which is making changes to the database.
-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
+The Dockerfile already defines a HEALTHCHECK command which will be used by software that
-that supports it. However if you wish to trigger a healthcheck yourself on a running
+supports it. However if you wish to trigger a healthcheck yourself on a running Baserow
-Baserow container then you can run:
+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
+Or you can just store it directly in the volume at `baserow_data/env` meaning it will be
-be loaded whenever you mount in this data volume.
+loaded whenever you mount in this data volume.
-
 
 ### Building your own image from Baserow