Skip to content

Install Mathesar via Docker Compose

Prerequisites

Operating System

You can install Mathesar using this method on Linux, MacOS, and Windows.

Access

You should have root access to the machine you’re installing Mathesar on.

Software

You’ll need to install the following software before you install Mathesar:

Domain (optional)

If you want Mathesar to be accessible over the internet, you’ll probably want to set up a domain or sub-domain to use. If you don’t need a domain, you can skip this section.

Before you start installation, ensure that the DNS for your sub-domain or domain is pointing to the machine that you’re installing Mathesar on.

Database (optional)

You can create a new PostgreSQL database while setting up Mathesar or use our UI to interact with an existing database. If you don’t have a database you want to connect to, you can skip this section.

To connect Mathesar to an existing database:

  • The external database should be able to accept network connections from your Mathesar server.
  • You’ll need to set up a database user for Mathesar to use. The user should be a SUPERUSER, see PostgreSQL docs for more information.
  • Have the following information handy before installation:
    • Database hostname
    • Database port
    • Database name
    • Database username
    • Database password

See Connect to an existing database for more details.

Step-by-Step Guide

  1. Navigate to a directory where you’d like to store your Mathesar configuration. We recommend /etc/mathesar, but it can be any directory.

    sudo mkdir -p /etc/mathesar
cd /etc/mathesar

  2. Download our docker-compose.yml, and .env.example files to the directory you’ve chosen.

    sudo wget https://github.com/centerofci/mathesar/raw/0.1.3/docker-compose.yml
sudo wget https://github.com/centerofci/mathesar/raw/0.1.3/.env.example

  3. Rename .env.example to .env

    sudo mv .env.example .env

    Your custom .env file will be used for setting configuration variables.

  4. Set up the database

  5. Set up the web server.

    1. Edit your .env file, making the following changes:

      Example

      If you are using the default database container, your .env file should look something like this

      ALLOWED_HOSTS='<your_domain_name>'
SECRET_KEY='dee551f449ce300ee457d339dcee9682eb1d6f96b8f28feda5283aaa1a21'
DJANGO_DATABASE_URL='postgresql://mathesar:mathesar@mathesar_db:5432/mathesar_django'
MATHESAR_DATABASES='(mathesar_tables|postgresql://mathesar:mathesar@mathesar_db:5432/mathesar)'

    2. Start the Mathesar web server.

      sudo docker compose -f docker-compose.yml up service -d

      docker compose -f docker-compose.yml up service -d

  6. Set up the Caddy reverse proxy.

    1. Edit your .env file, adding the Caddy Reverse Proxy environment variables.

    2. Start the Caddy reverse proxy

      sudo docker compose -f docker-compose.yml up caddy-reverse-proxy -d

      docker compose -f docker-compose.yml up caddy-reverse-proxy -d

  7. (Optional) Start the upgrade server to enable upgrading the docker image using the Mathesar UI.

    sudo docker compose -f docker-compose.yml up watchtower -d

    docker compose -f docker-compose.yml up watchtower -d

  8. Set up your user account

    Mathesar is now installed! You can use it by visiting localhost or the domain you’ve set up.

    You’ll be prompted to set up an admin user account the first time you open Mathesar. Just follow the instructions on screen.

Starting and stopping Mathesar

The Mathesar server needs to be running for you to use Mathesar. If you restart your machine, you’ll need to start the server again.

  • Start Mathesar:

    sudo docker compose -f /etc/mathesar/docker-compose.yml up -d

    docker compose -f /etc/mathesar/docker-compose.yml up -d

  • Stop Mathesar:

    sudo docker compose -f /etc/mathesar/docker-compose.yml down

    docker compose -f /etc/mathesar/docker-compose.yml down

    This stops all Mathesar Docker containers and releases their ports.

Note

If you customized the Mathesar configuration directory during installation, you’ll need to change /etc/mathesar to your configuration directory.

Upgrading Mathesar

Upgrade from within Mathesar

You can also run the upgrade from within Mathesar by logging in as an admin user and navigating to “Administration” (in the top right menu) > “Software Update”

Manually upgrade Mathesar to the newest version using Watchtower:

sudo docker exec mathesar-watchtower-1 /watchtower --run-once

docker exec mathesar-watchtower-1 /watchtower --run-once

Manually upgrade Mathesar to the newest version without using Watchtower:

sudo docker compose -f docker-compose.yml up --force-recreate --build service

docker compose -f docker-compose.yml up --force-recreate --build service

Uninstalling Mathesar

  1. Remove all Mathesar Docker images and containers.

    sudo docker compose -f /etc/mathesar/docker-compose.yml down --rmi all -v

    docker compose -f /etc/mathesar/docker-compose.yml down --rmi all -v

  2. Remove configuration files.

    sudo rm -rf /etc/mathesar

    Note

    If you customized the Mathesar configuration directory during installation, you’ll need to change /etc/mathesar to your configuration directory.

  3. Remove Mathesar internal schemas.

    If you’d like to continue using your PostgreSQL database, you’ll need to remove the schemas created for Mathesar’s use during installation. You can remove them from the database as follows:

    1. Connect to the database.

      psql -h <DB HOSTNAME> -p <DB PORT> -U <DB_USER> <DB_NAME>

    2. Delete the types schema.

      DROP SCHEMA mathesar_types CASCADE;

      Deleting this schema will also delete any database objects that depend on it. This should not be an issue if you don’t have any data using Mathesar’s custom data types.

    3. Delete the function schemas.

      DROP SCHEMA msar CASCADE;
DROP SCHEMA __msar CASCADE;