Install Mathesar web server via Docker¶

Use our official Docker image: mathesar/mathesar-prod:latest hosted on Docker Hub to run Mathesar.

Limitations

This installation procedure is intended for users who want to run a bare-bones version of the Mathesar web server.

It is assumed you already have a database server and services like a reverse proxy typically needed for running a production setup. If you don’t have those, please use the Docker Compose installation documentation.

Prerequisites¶

Operating System¶

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

Access¶

You should have permission to run Docker containers on the system.

Software¶

You’ll need to install Docker v23+

Databases¶

Database for Mathesar’s internal usage¶

You’ll need to:

Create a PostgreSQL database for Mathesar’s internal usage.
Create a database user for Mathesar to use. The user should be a SUPERUSER, see PostgreSQL docs for more information.
Ensure that this database can accept network connections from the machine you’re installing Mathesar on.
Have the following information for this database handy before installation:
- Database hostname
- Database port
- Database name
- Database username
- Database password

Databases connected to Mathesar’s UI¶

Have the following information for all databases you’d like to connect to Mathesar’s UI before installation:

Database hostname
Database port
Database name
Database username (should be a SUPERUSER, see above)
Database password

Database creation

Whenever the Docker container is started, we will attempt to create any databases in this list that don’t already exist. So you don’t need to ensure that they are created before installation.

Installation Steps¶

Run the Mathesar Docker Image
```
docker run \
  --detach
  -e DJANGO_DATABASE_URL='<replace with a postgres connection string>' \
  -e MATHESAR_DATABASES='(<unique_db_key>|<replace with a postgres connection array>)' \
  -e SECRET_KEY='<replace with a 50 character string>' \
  -e ALLOWED_HOSTS='.localhost, 127.0.0.1, [::1]' \
  -v static:/code/static \
  -v media:/code/media \
  --name mathesar_service \
  -p 8000:8000 \
  --restart unless-stopped \
  mathesar/mathesar-prod:latest
```
The above command creates a Docker container containing the Mathesar server running on the localhost and listening on port 8000. It also:
- Passes configuration options as environment variables to the Docker container. Refer to Configuring Mathesar web server for setting the correct value to these configuration options and for additional configuration options. The configuration options used in the above command are:
  - DJANGO_DATABASE_URL
  - DJANGO_DATABASE_KEY
  - MATHESAR_DATABASES
  - SECRET_KEY
- Creates two named Docker volumes
  - static for storing static assets like CSS, js files
  - media for storing user-uploaded media files
- Sets the container name as mathesar_service using the --name parameter, runs the container in a detached mode using the --detach parameter, and binds the port 8000 to the localhost. Refer to Docker documentation for additional configuration options.
Verify if the Mathesar server is running successfully:
```
docker logs -f mathesar_service
```
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.

Upgrading Mathesar¶

Stop your existing Mathesar container:
```
docker stop mathesar_service
```
Remove the old Mathesar Image
```
docker rm mathesar_service
```

Bump the image version in the docker run command you usually use to run your Mathesar and start up a brand-new container:

docker run \
  -d \
  --name mathesar_service \
  # YOUR STANDARD ARGS HERE
  mathesar/mathesar-prod:latest

Uninstalling Mathesar¶

Remove the Mathesar container.
```
docker rm -v mathesar_service
```
Remove the Mathesar Image
```
docker rmi mathesar_service
```

Remove volumes related to Mathesar

docker volume rm static &&
docker volume rm media

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;
```