Install Mathesar from source on Linux¶

Not a stable release

This is a testing build released with the goal of gathering feedback from our community. It has many known issues and is not recommended for production use.

For experienced Linux sysadmins

To follow this guide you need be experienced with Linux server administration, including the command line interface and some common utilities.

If you run into any trouble, we encourage you to open an issue or submit a PR proposing changes to this file.

Requirements¶

System¶

We recommend having at least 60 GB disk space and 4 GB of RAM.

Operating System¶

We’ve tested this on Debian 12, but we expect that it can be adapted for other Linux distributions as well.

Access¶

You should have root access to the machine you’re installing Mathesar on.

Software¶

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

Python 3.9, 3.10, or 3.11 (along with appropriate venv module)

Python version

Python older than 3.9 will not run Mathesar.

Python 3.12 will run Mathesar, but you’ll have to take extra steps to get some dependencies to build. Installing a package for your OS that provides the libpq-fe.h header file should be enough in most cases. On Debian 12, this header is provided by the libpq-dev package.
PostgreSQL 13 or newer (Verify by logging in, and running the query: SELECT version();)
Caddy (Verify with caddy version)
git (Verify with git --version)
GNU gettext (Verify with gettext --version)
unzip A utility tool to de-archive .zip files (Verify with unzip -v)

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.

Customizing this Guide¶

Type your domain name into the box below. Do not include a trailing slash.

Then press Enter to customize this guide with your domain name.

Installation Steps¶

Set up the database¶

Open a psql shell.

sudo -u postgres psql  # Modify based on your Postgres installation.

Let’s create a Postgres user for Mathesar
```
CREATE USER mathesar WITH ENCRYPTED PASSWORD '1234';
```
Customize your password

Be sure to change the password 1234 in the command above to something more secure and private. Record your custom password somewhere safe. You will need to reference it later.
Next, we have to create a database for storing Mathesar metadata. Your PostgreSQL user will either need to be a SUPERUSER or OWNER of the database. In this guide, we will be setting the user to be OWNER of the database as it is slightly restrictive compared to a SUPERUSER.
```
CREATE DATABASE mathesar_django OWNER mathesar;
```
Press Ctrl+D to exit the psql shell.

Set up your installation directory¶

Choose a directory to store the Mathesar application files.
Examples
- /home/my_user_name/mathesar
- /etc/mathesar
Type your installation directory into the box below. Do not include a trailing slash.

Then press Enter to customize this guide with your installation directory.
Create your installation directory.
```
mkdir -p xMATHESAR_INSTALLATION_DIRx
```
When installing outside your home folder

If you choose a directory outside your home folder, then you’ll need to create it with sudo and choose an appropriate owner for the directory (i.e. root or a custom user of your choosing).

The remainder of this guide requires you to run commands with full permissions inside your installation directory. You can do this, for example via:
- chown my_user_name: xMATHESAR_INSTALLATION_DIRx
  
  Or
- sudo su
Navigate into your installation directory.
```
cd xMATHESAR_INSTALLATION_DIRx
```
The remaining commands in this guide should be run from within your installation directory.

Set up the environment¶

Clone the git repo into the installation directory.

git clone https://github.com/mathesar-foundation/mathesar.git .

Check out the tag of the release or build you’d like to install, 0.2.0-testing.1.
```
git checkout 0.2.0-testing.1
```
Important

If you don’t run the above command you’ll end up installing the latest development version of Mathesar.

We need to create a python virtual environment for the Mathesar application.

<path-to-python-binary> -m venv ./mathesar-venv
# /usr/bin/python3.9 -m venv ./mathesar-venv

Next we will activate our virtual environment:
```
source ./mathesar-venv/bin/activate
```
Important

You need to activate the environment each time you restart the shell as they don’t persist across sessions.

Install the Mathesar application¶

Install Python dependencies
```
pip install -r requirements-prod.txt
```
Set the environment variables
1. Create .env file
```
touch .env
```
2. Edit your .env file, adding environment variables to configure Mathesar.
  Example
  
  Your .env file should look something like this
```
SECRET_KEY='REPLACE_THIS_WITH_YOUR_RANDOMLY_GENERATED_VALUE'
DOMAIN_NAME='xDOMAIN_NAMEx'
ALLOWED_HOSTS='xDOMAIN_NAMEx'
POSTGRES_DB=mathesar_django
POSTGRES_USER=mathesar
POSTGRES_PASSWORD=REPLACE_THIS_WITH_APPROPRIATE_PASSWORD_FOR_THE_CHOSEN_POSTGRES_USER
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
```
  Tip
  
  To generate a SECRET_KEY you can use this browser-based generator or run this command on MacOS or Linux:
```
echo $(cat /dev/urandom | LC_CTYPE=C tr -dc 'a-zA-Z0-9' | head -c 50)
```
  Tip
  
  If you want to host Mathesar on multiple domains/subdomains you can do so by adding multiple comma separated domain names to the following env variables without a whitespace:
```
DOMAIN_NAME='xDOMAIN_NAMEx,xDOMAIN_NAMEx.example.org'
ALLOWED_HOSTS='xDOMAIN_NAMEx,xDOMAIN_NAMEx.example.org'
```
3. Add the environment variables to the shell
  
  You need to export the environment variables listed in the .env file to your shell. The easiest way would be to run the below command.
```
export $(cat .env)
```
  Important
  
  You need to export the environment variables each time you restart the shell as they don’t persist across sessions.

Download release static files and extract into the correct directory

wget https://github.com/mathesar-foundation/mathesar/releases/download/0.2.0-testing.1/static_files.zip
unzip static_files.zip && mv static_files mathesar/static/mathesar && rm static_files.zip

Compile Mathesar translation files
```
python manage.py compilemessages
```

Install Mathesar functions on the database:

python -m mathesar.install --skip-confirm | tee /tmp/install.py.log

Create a media directory for storing user-uploaded media
```
mkdir .media
```

Set up Gunicorn¶

Elevated permissions needed

Most of the commands below need to be run as a root user, or using sudo. If you try to run one of these commands, and see an error about “permission denied”, use one of those methods.

Create a user for running Gunicorn

groupadd gunicorn && \
useradd gunicorn -g gunicorn

Make the gunicorn user the owner of the .media directory
```
chown -R gunicorn:gunicorn .media/
```

Create the Gunicorn SystemD service file.

touch /lib/systemd/system/gunicorn.service

and copy the following code into it.

[Unit]
Description=gunicorn daemon
After=network.target network-online.target
Requires=network-online.target

[Service]
Type=notify
User=gunicorn
Group=gunicorn
RuntimeDirectory=gunicorn
WorkingDirectory=xMATHESAR_INSTALLATION_DIRx
ExecStart=/bin/bash -c 'xMATHESAR_INSTALLATION_DIRx/mathesar-venv/bin/gunicorn config.wsgi:application'
EnvironmentFile=xMATHESAR_INSTALLATION_DIRx/.env

[Install]
WantedBy=multi-user.target

Reload systemctl and start the Gunicorn socket

systemctl daemon-reload
systemctl start gunicorn.service
systemctl enable gunicorn.service

Check the logs to verify if Gunicorn is running without any errors
```
journalctl --unit=gunicorn.service
```

Set up the Caddy reverse proxy¶

We will use the Caddy Reverse proxy to serve the static files and set up SSL certificates.

Create the CaddyFile
```
touch /etc/caddy/Caddyfile
```

Add the configuration details to the CaddyFile

$DOMAIN_NAME {
    log {
        output stdout
    }
    respond /caddy-health-check 200
    encode zstd gzip
    handle_path /media/* {
        @downloads {
            query dl=*
        }
        header @downloads Content-disposition "attachment; filename={query.dl}"

        file_server {
            precompressed br zstd gzip
            root {$MEDIA_ROOT:xMATHESAR_INSTALLATION_DIRx/.media/}
        }
    }
    handle_path /static/* {
        file_server {
            precompressed br zstd gzip
            root {$STATIC_ROOT:xMATHESAR_INSTALLATION_DIRx/static/}
        }
    }
    reverse_proxy localhost:8000
}

Create a user for running Caddy

groupadd caddy && \
useradd caddy -g caddy

Create the Caddy systemd service file.

touch /lib/systemd/system/caddy.service

and copy the following code into it.

[Unit]
Description=Caddy
Documentation=https://caddyserver.com/docs/
After=network.target network-online.target
Requires=network-online.target

[Service]
Type=notify
User=caddy
Group=caddy
ExecStart=/usr/bin/caddy run --config /etc/caddy/Caddyfile
ExecReload=/usr/bin/caddy reload --config /etc/caddy/Caddyfile --force
TimeoutStopSec=5s
LimitNOFILE=1048576
LimitNPROC=512
PrivateTmp=true
ProtectSystem=full
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

Reload the systemctl and start the Caddy socket

systemctl daemon-reload && \
systemctl start caddy.service && \
systemctl enable caddy.service

Check the logs to verify if Caddy is running without any errors
```
journalctl --unit=caddy.service
```

Set up your user account¶

Mathesar is now installed! You can use it by visiting the URL xDOMAIN_NAMEx.

You’ll be prompted to set up an admin user account the first time you open Mathesar. Follow the instructions on screen.