Skip to content

Install Mathesar via Docker Compose

Requirements

  • You need Docker and Docker Compose.

    We’ve tested with Docker v23 and Docker Compose v2.10. Older versions may not work.

  • You need root access.

  • If using a custom domain name

    Have your domain name ready during the installation process and have your DNS pointing to your Mathesar server.

  • If connecting to an existing database

    • Ensure the external database can accept network connections from your Mathesar server.

    • Have the following information handy before installation:

      • Database hostname (cannot yet be localhost)
      • Database port
      • Database name
      • Database username (should exist and be a SUPERUSER more info)
      • Database password

  • If installing on Windows, you need to have WSL installed first.

Install

  1. Paste this command into your terminal to begin installing the latest version of Mathesar:

    bash <(curl -sfSL https://raw.githubusercontent.com/centerofci/mathesar/0.1.1/install.sh)

  2. Follow the interactive prompts to configure your Mathesar installation.

  3. When finished, the installer will display the URL where you can run Mathesar from your web browser.

Getting help

If you run into any problems during installation, see troubleshooting or open a ticket describing your problem.

Start/stop the server

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 --profile prod up -d

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

  • Stop Mathesar:

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

    docker compose -f /etc/mathesar/docker-compose.yml --profile prod 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.

Upgrade

Manually upgrade Mathesar to the newest version:

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

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

Upgrade from within Mathesar

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

Uninstall

  1. Remove all Mathesar Docker images and containers.

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

    docker compose -f /etc/mathesar/docker-compose.yml --profile prod 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 connected Mathesar to an existing database, the installation process would have created a new schema for Mathesar’s use. You can remove this schema from that database as follows:

    1. Connect to the database.

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

    2. Delete the schema.

      DROP SCHEMA mathesar_types CASCADE;

      Danger

      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.