Skip to content

Guided installation

Our install script guides you through a series of prompts to install Mathesar. The script sets up Mathesar using Docker Compose under the hood.

Limitations

This is a convenient way to install Mathesar. However, it’s highly opinionated and requires sudo privileges (admin access), and only supports a limited set of configuration options. Use the Docker Compose installation option if you’d like to customize your installation.

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.

Overview

The installation script will set up:

  • A Postgres database server to store data
  • A web server to run the Mathesar application
  • A reverse proxy server to serve static files and set up SSL certificates
  • An upgrade server to handle upgrading Mathesar via the web interface

If you’d like to know the steps performed by the install script in more detail, you can read our Guided installation: under the hood document.

Step-by-step guide

Getting help

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

  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.3/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.

Connecting to additional databases

Once you have successfully installed Mathesar, if you wish to connect an additional database to Mathesar, instructions are here.

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;