Skip to content

Install Mathesar via Docker Compose

Prerequisites

Operating System

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

Software

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

Step-by-Step Guide

Note

Depending on your Docker setup, you may need to run docker commands with sudo.

Video walkthrough (Click to expand)

  1. Download our docker-compose.yml file.

    wget https://github.com/mathesar-foundation/mathesar/raw/0.1.4/docker-compose.yml
    
  2. Open the downloaded docker-compose file using your text editor.

  3. Set the required environment variables in the x-config section of the docker compose file.

    Config

    x-config: &config
      # (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.
      # 'yourdomain.com, 127.0.0.1' to manage the host(s) at which you want to
      # access Mathesar over http or https
      DOMAIN_NAME: ${DOMAIN_NAME:-http://localhost}
    
      # Edit the POSTGRES_* variables if you are not using the db service provided
      # below, or if you want to use a custom database user.
    
      # (Optional) Replace 'mathesar_django' with any custom name for the internal
      # database managed by mathesar web-service
      POSTGRES_DB: ${POSTGRES_DB:-mathesar_django}
    
      # (Optional) Replace 'mathesar' with any custom username for the
      # aforementioned database
      POSTGRES_USER: ${POSTGRES_USER:-mathesar}
    
      # (Optional) Replace 'mathesar' with any custom password for the
      # aforementioned database
    
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-mathesar}
      # (Optional) Replace 'mathesar_db' with the name of the host running postgres
      POSTGRES_HOST: ${POSTGRES_HOST:-mathesar_db}
    
      # (Optional) Replace '5432' with the port on which postgres is running
      POSTGRES_PORT: ${POSTGRES_PORT:-5432}
    
  4. Run the docker compose file using:

    docker compose -f docker-compose.yml up
    

  5. 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:

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

    Info

    Exclude the -d flag if you’d like to see the container’s logs.

  • Stop Mathesar:

    docker compose -f docker-compose.yml down
    

    This stops all Mathesar Docker containers and releases their ports.

Optional configurations

Hosting Mathesar over a custom domain with https

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.

Ensure that the DNS for your domain or sub-domain is pointing to the public IP address of the machine that you’re installing Mathesar on.

Add your domain(s) or sub-domain(s) to the DOMAIN_NAME environment variable, in the CONFIG section of the docker-compose file.

Example

DOMAIN_NAME: ${DOMAIN_NAME:-yourdomain.org, yoursubdomain.example.org}

Restart the docker containers for the configuration to take effect.

Using an external PostgreSQL server for Mathesar’s internal database

If you’d like to use an external PostgreSQL server for Mathesar’s internal database, you’ll need to do the following:

  1. On the existing database server, create a new database for Mathesar to store its metadata.

    psql -c 'create database mathesar_django;'
    
  2. Configure the internal database environment variables to point to the database you just created. Ensure that you change the default values for the user, password, and host.