Version 0.1.4

docker-compose.yml

@@ -28,11 +28,13 @@ version: "3.9"
 #-------------------------------------------------------------------------------
 # CONFIG
 #
-# Customize your Mathesar installation with the following variables, if desired.
+# Customize your Mathesar installation with the following variables.
+# See https://docs.mathesar.org/configuration/env-variables/ for more info.
 #
 x-config: &config
-  # (Required) Replace '?' with '-' followed by a 50 character random string.
-  # You can generate one at https://djecrety.ir/
+  # (REQUIRED) Replace '?' with '-' followed by a 50 character random string.
+  # You can generate one at https://djecrety.ir/ or by running:
+  #   echo $(cat /dev/urandom | LC_CTYPE=C tr -dc 'a-zA-Z0-9' | head -c 50)
   SECRET_KEY: ${SECRET_KEY:?}
 
   # (Optional) Replace 'http://localhost' with custom domain(s) e.g.

docs/docs/administration/uninstall.md

@@ -2,7 +2,98 @@
 
 The uninstall instructions vary depending on the [installation method](../index.md#installing-mathesar) you chose. Select your installation method below to proceed.
 
-- [Uninstall a **guided** installation of Mathesar](../installation/guided-install/index.md#uninstall)
-- [Uninstall a **Docker compose** installation of Mathesar](../installation/docker-compose/index.md#uninstall)
-- [Uninstall a **Docker** installation of Mathesar](../installation/docker/index.md#uninstall)
-- [Uninstall a **source-built** installation of Mathesar](../installation/build-from-source/index.md#uninstall)
+## Uninstall a Docker installation of Mathesar
+
+!!!note
+    Depending on your Docker setup, you may need to run `docker` commands with `sudo`.
+
+1. Remove the Mathesar container.
+
+    ```
+    docker rm -v mathesar_service
+    ```
+
+1. Remove the Mathesar Image
+
+    ```
+    docker rmi mathesar_service
+    ```
+
+1. Remove volumes related to Mathesar
+
+    ```
+    docker volume rm static &&
+    docker volume rm media
+    ```
+
+{% include 'snippets/uninstall-schemas.md' %}
+
+
+## Uninstall a Guided script or Docker compose installation of Mathesar
+
+1. Remove all Mathesar Docker images and containers.
+
+    ```
+    docker compose -f docker-compose.yml down --rmi all -v
+    ```
+
+1. Remove configuration files.
+
+    ```
+    rm -rf xMATHESAR_INSTALLATION_DIRx  # may need sudo, depending on location
+    ```
+
+{% include 'snippets/uninstall-schemas.md' %}
+
+## Uninstall a source installation of Mathesar
+
+1. Stop Caddy service
+
+    ```
+    systemctl disable caddy.service && systemctl stop caddy.service
+    ```
+
+1. Remove Caddy service file and Caddyfile (requires `sudo`)
+
+    ```
+    sudo rm /lib/systemd/system/caddy.service
+    sudo rm /etc/caddy/Caddyfile
+    ```
+
+1. Stop Gunicorn
+
+    ```
+    systemctl disable gunicorn.service
+    systemctl stop gunicorn.service
+    ```
+
+1. Remove Gunicorn service file
+
+    ```
+    sudo rm /lib/systemd/system/gunicorn.service
+    ```
+
+1. Remove your Mathesar installation directory
+
+    ```
+    rm -r xMATHESAR_INSTALLATION_DIRx  # May need sudo, depending on location
+    ```
+
+    !!! warning "Your installation directory might be customized"
+        It's possible that Mathesar could have been installed into a different directory than shown above. Use caution when deleting this directory.
+
+1. Remove Django database
+
+    1. Connect to the psql terminal.
+
+        ```
+        sudo -u postgres psql
+        ```
+
+    2. Drop the Django database.
+
+        ```postgresql
+        DROP DATABASE mathesar_django;
+        ```
+
+{% include 'snippets/uninstall-schemas.md' %}

docs/docs/administration/upgrade/0.1.4.md

@@ -0,0 +1,206 @@
+# Upgrade Mathesar to 0.1.4
+
+The 0.1.4 release requires more upgrade steps than we hope to have for future releases! If you run into any trouble, we encourage you to [open an issue](https://github.com/mathesar-foundation/mathesar/issues/new/choose) or [contact us](https://mathesar.org/free-install.html) for help.
+
+## For installations using Docker Compose {:#docker-compose}
+
+If you followed our [Docker Compose installation instructions](../../installation/docker-compose/index.md), then use these steps to upgrade your installation to 0.1.4.
+
+!!! note
+    Depending on your setup, you may need to run some commands with `sudo`.
+
+1. Find needed parts
+
+    1. Find your `.env` and `docker-compose.yml` files. Run
+
+        ```
+        docker inspect mathesar_service 
+        ```
+
+        and look for the value of the `"com.docker.compose.project.config_files"` key in the resulting JSON to find the path to the `docker-compose.yml` file. The `.env` file should be in the same directory. If you have `jq` installed, you can run
+
+        ```
+        docker inspect mathesar_service \
+          | jq '.[0].Config.Labels."com.docker.compose.project.config_files"'
+        ```
+
+        and get the path directly. The `.env` file should be in the same directory.
+
+    1. Copy the path of the directory containing `docker-compose.yml` and `.env` into the box below. Do not include a trailing slash.
+
+        <input data-input-for="MATHESAR_INSTALLATION_DIR" aria-label="Your Mathesar installation directory"/>
+
+        Then press <kbd>Enter</kbd> to customize this guide with the configuration directory.
+
+    1. If you are using a Docker container for your PostgreSQL database, Run
+
+        ```
+        docker volume inspect mathesar_postgresql_data
+        ```
+
+        and look for the `"Mountpoint"` in the resulting JSON.
+
+    1. Copy the path of the directory into the box below. Do not include a trailing slash.
+
+        <input data-input-for="MATHESAR_PG_DIR" aria-label="Your Mathesar Postgres data directory"/>
+
+        Then press <kbd>Enter</kbd> to customize this guide with the PostgreSQL data directory.
+
+1. Stop Mathesar, remove old images
+
+    ```
+    docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml down --rmi all
+    ```
+
+1. Set up new configuration
+
+    !!! warning
+        `MATHESAR_DATABASES` has been deprecated as of v0.1.4 and will be removed entirely in future releases of Mathesar. If you end up deleting the variable from your `.env` file before starting up Mathesar after the upgrade, you can still add the connections manually through Mathesar's UI.
+
+    1. Back up the old configuration files:
+
+        ```
+        mv xMATHESAR_INSTALLATION_DIRx/docker-compose.yml xMATHESAR_INSTALLATION_DIRx/docker-compose.yml.backup
+        cp xMATHESAR_INSTALLATION_DIRx/.env xMATHESAR_INSTALLATION_DIRx/env.backup
+        ```
+
+        (We'll modify the old file, so we copy instead of moving it.)
+
+    1. Download the new docker compose file:
+
+        ```
+        curl -sfL -o xMATHESAR_INSTALLATION_DIRx/docker-compose.yml https://raw.githubusercontent.com/mathesar-foundation/mathesar/0.1.4/docker-compose.yml
+        ```
+
+    1. Edit the `xMATHESAR_INSTALLATION_DIRx/.env` file to break the `DJANGO_DATABASE_URL` variable into its parts.
+
+        This variable should have the form:
+
+        ```
+        DJANGO_DATABASE_URL=postgres://<username>:<password>@<host>:<port>/<database>
+        ```
+
+        You should edit the `.env` file to have the variables:
+
+        ```
+        POSTGRES_USER=<username>
+        POSTGRES_PASSWORD=<password>
+        POSTGRES_HOST=<host>
+        POSTGRES_PORT=<port>
+        POSTGRES_DB=<database>
+        ```
+
+        If you don't want to set those environment variables (e.g., if they're otherwise used), you can instead edit the `docker-compose.yml` file directly to add those variables.
+
+    1. Double-check the rest of the configuration:
+
+        - You should have your [`SECRET_KEY` variable](../../configuration/env-variables.md#secret_key) defined.
+        - If hosting on the internet, you should have a `DOMAIN_NAME` variable defined.
+
+1. Initialize new Mathesar installation
+
+    ```
+    docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml up -d
+    ```
+
+    This will pull new images, and start the Mathesar containers. Wait a few minutes, then run `docker ps` to verify that you have `mathesar_service`, `mathesar-caddy-reverse-proxy-1`, and `mathesar_db` running and that the service is healthy. The services should not be reporting errors. If you were _not_ using Docker volumes for your Mathesar PostgreSQL data, you're done, and you can login to Mathesar via your usual method. If you're not sure, try to login to Mathesar. If you're presented with a screen instructing you to create an Admin user, you likely need to proceed to the next step.
+
+1.  Move your PostgreSQL directory
+
+    1. Bring down the services:
+
+        ```
+        docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml down
+        ```
+
+    1. Remove scaffold database data, copy your old PostgreSQL volume to the new location:
+
+        ```
+        rm -r xMATHESAR_INSTALLATION_DIRx/msar/pgdata
+        cp -r xMATHESAR_PG_DIRx xMATHESAR_INSTALLATION_DIRx/msar/pgdata
+        ```
+
+    1. Bring the services back up:
+
+        ```
+        docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml up -d
+        ```
+
+1. If things look good, then you can try to login at the usual address using your normal username and password, and you should see your data.
+
+## For installations done via our guided script {:#guided}
+
+If you installed Mathesar with our (now deprecated) guided script, then you have a Docker Compose installation. See the [Docker Compose upgrade steps](#docker-compose).
+
+
+## For installations done from scratch {:#scratch}
+
+If you installed Mathesar [from scratch](../../installation/build-from-source/index.md), then use these steps to upgrade your installation to 0.1.4.
+
+!!! warning
+    These steps have not yet been tested extensively. If you run into any trouble, we encourage you to [open an issue](https://github.com/mathesar-foundation/mathesar/issues/new/choose) or submit a PR proposing changes to [this file](https://github.com/mathesar-foundation/mathesar/blob/master/docs/docs/administration/upgrade/0.1.4.md).
+
+1. Go to your Mathesar installation directory.
+
+    ```
+    cd xMATHESAR_INSTALLATION_DIRx
+    ```
+
+    !!! note
+        Your installation directory may be different from above if you used a different directory when installing Mathesar.
+
+1. Pull the latest version from the repository
+
+    ```
+    git pull https://github.com/mathesar-foundation/mathesar.git
+    ```
+
+1. Update Python dependencies
+
+    ```
+    pip install -r requirements.txt
+    ```
+
+1. Next we will activate our virtual environment:
+
+    ```
+    source ./mathesar-venv/bin/activate
+    ```
+
+1. Update your environment variables according to the [the new configuration specification](../../configuration/env-variables.md#db). In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported.
+
+1. Add the environment variables to the shell before running Django commands
+
+    ```
+    export $(sudo cat .env)
+    ```
+
+1. Run the latest Django migrations
+
+    ```
+    python manage.py migrate
+    ```
+
+1. Install the frontend dependencies
+
+    ```
+    npm ci --prefix mathesar_ui
+    ```
+
+1. Build the Mathesar frontend app
+
+    ```
+    npm run --prefix mathesar_ui build --max_old_space_size=4096
+    ```
+
+1. Update Mathesar functions on the database:
+
+    ```
+    python mathesar/install.py --skip-confirm >> /tmp/install.py.log
+    ```
+
+1. Restart the gunicorn server
+
+    ```
+    systemctl restart gunicorn
+    ```

docs/docs/administration/upgrade/older.md

@@ -0,0 +1,17 @@
+# Upgrading Mathesar to older versions
+
+## For installations using Docker Compose {:#docker-compose}
+
+If you have a Docker compose installation (including one from the guided script), run the command below:
+
+```
+docker compose -f /etc/mathesar/docker-compose.yml up \
+  --force-recreate --build service
+```
+
+!!! note "Your installation directory may be different"
+    You may need to change `/etc/mathesar/` in the command above if you chose to install Mathesar to a different directory.
+
+## For installations done from scratch {:#scratch}
+
+If you installed from scratch, the upgrade instructions are the same as [for 0.1.4](../upgrade/0.1.4.md#scratch), but you do not need to change the environment variables.

docs/docs/configuration/connect-to-existing-db.md

@@ -6,15 +6,13 @@
     psql -c 'create database mathesar_django;'
     ```
 
-1. Configure the [`DJANGO_DATABASE_URL` environment variable](./env-variables.md#django_database_url) to point to the database you just created.
-
-1. (Optional) For Docker Compose related installations, you may [disable Mathesar's default database server](./customize-docker-compose.md#disable-db-service) if you like.
+1. Configure the [Internal database environment variables](./env-variables.md#db) to point to the database you just created.
 
 
 ## Connect to a database server running on the host {: #localhost-db }
 
 !!! info ""
-    This content is related to Mathesar running in Docker related environments. This is applicable for the [Guided installation method](../installation/guided-install/index.md), [Docker Compose installation method](../installation/docker-compose/index.md), and [Docker installation method](../installation/docker/index.md).
+    This content is related to Mathesar running in Docker related environments.
 
 If you're running Mathesar in a Docker related environment, and your database server runs on the host machine, you will not be able to connect to it using `localhost:<db_port>`, since `localhost` would refer to the Docker environment and not to the host.
 
@@ -67,7 +65,7 @@ You can try using `host.docker.internal` instead of `localhost`. Below are detai
 
     === "Linux"
         ```
-        sudo systemctl restart postgresql
+        systemctl restart postgresql
         ```
     === "MacOS"
         ```