Skip to content

Customize Docker Compose related installations

This document is related to Mathesar running in Docker Compose related environments. This is applicable for the Guided Installation method, and Docker Compose Installation method.

Default database server

The default docker-compose.yml includes a db service that automatically starts a Postgres database server container called mathesar_db. This service allows you to start using Mathesar immediately to store data in a Postgres database without administering a separate Postgres server outside Mathesar.

The db service runs on the internal docker compose port 5432. The internal port is not bound to the host to avoid conflicts with other services running on port 5432.

Additionally, it comes with a default database and a superuser. This database can come in handy for storing Mathesar’s metadata. The credentials for the Default database are:


you can disable the default database server if you plan on using an existing database server.

Disable the default database server

The default docker-compose.yml automatically starts a Postgres database server container. You may disable it if you plan on using a different Database server.

In the docker-compose.yml file, comment out the db services and the depends_on field of the service.

  # db:
  #   image: postgres:13
  #   container_name: mathesar_db
  #   environment:
  #   # These environment variables are used to create a database and superuser when the `db` service starts.
  #   # Refer to for more information on these variables.
  #     - POSTGRES_DB=${POSTGRES_DB-mathesar_django}
  #     - POSTGRES_USER=${POSTGRES_USER-mathesar}
  #   expose:
  #     - "5432"
  #   volumes:
  #     - postgresql_data:/var/lib/postgresql/data
  #   healthcheck:
  #     test: [ "CMD-SHELL", "pg_isready -d $${POSTGRES_DB-mathesar_django} -U $${POSTGRES_USER-mathesar}"]
  #     interval: 5s
  #     timeout: 1s
  #     retries: 30
  #     start_period: 5s

  # ...
    # ...
      - static:/code/static
      - media:/code/media
    # Comment the below field to disable starting the database service automatically
    # depends_on:
    #   db:
    #    condition: service_healthy

After this change, Mathesar will no longer start the db service automatically.

Run Mathesar on a non-standard HTTP port

By default, Caddy serves the Mathesar web application on a port as determined by the protocol within your DOMAIN_NAME environment variable.

  • For http domain names it uses port 80.
  • For https domain names (as is the default, if not specified) it uses port 443 and redirects any traffic pointed at http to https. In this case, Caddy also creates an SSL certificate automatically.


    If you don’t have access to port 443, avoid using https domain names on a non-standard port. Due to the following reasons:

    • Caddy won’t be able to verify the SSL certificate when running on a non-standard port.
    • Browsers automatically redirect traffic sent to the http domain to the standard https port (443), rather than to any non-standard HTTPS_PORT port that you may have configured.

To use a non-standard port:

  1. Edit your .env file and set either the HTTP_PORT or the HTTPS_PORT environment variable (depending on the protocol you’re using).


    To serve Mathesar at http://localhost:9000, include the following in your .env file:

  2. Restart the container

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