Axemere.ai

PostgreSQL Setup

For: Database administrators and platform engineers setting up the Postgres database for Axemere Gateway.

IT Setup Overview | PostgreSQL Setup | Linux (Debian/Ubuntu) | Linux (RHEL/Fedora) | macOS | Docker/Podman | Kubernetes | Windows (WSL2) | Cloud

All Axemere Gateway deployment methods require an external PostgreSQL 15+ instance. The gateway binary does not bundle or install a database server.

Schema migrations run automatically on startup using idempotent CREATE TABLE IF NOT EXISTS statements. No manual migration step is required -- simply start the gateway and it will create all necessary tables.

Before starting the gateway you need:

  • A running PostgreSQL 15+ server (self-hosted or managed)
  • A database and a user with CREATE TABLE / CREATE INDEX privileges on that database
  • A DATABASE_URL connection string pointing at it

Table of Contents

Generate a password first

Paste this into your terminal and save the output -- you will use it in the steps below:

openssl rand -hex 16
# example output: 4a7f3c8e9b1d2f60a5c4e3b2d1f0e8a7

Using a hex password avoids special characters that would need URL-encoding in DATABASE_URL.

Option A -- Docker (quickest, any platform)

If Docker is already installed, this is the fastest path. No PostgreSQL knowledge required.

docker run -d \
  --name mvgc-postgres \
  --restart unless-stopped \
  -e POSTGRES_USER=mvgc_gateway \
  -e POSTGRES_PASSWORD=<your-generated-password> \
  -e POSTGRES_DB=mvgc_gateway \
  -p 5432:5432 \
  postgres:16-alpine

Your DATABASE_URL:

# Format: postgres://<user>[:<password>]@<host>[:<port>]/<database>?sslmode=<disable|require>
DATABASE_URL=postgres://mvgc_gateway:<your-generated-password>@localhost:5432/mvgc_gateway?sslmode=disable

Option B -- Ubuntu / Debian (bare metal)

# 1. Install PostgreSQL
sudo apt install -y postgresql

# 2. Confirm the service is running
sudo systemctl enable --now postgresql
sudo systemctl status postgresql   # should show "active (running)"

# 3. Create the database user and database
#    (postgres is a superuser created automatically during install)
sudo -u postgres psql <<'EOF'
CREATE USER mvgc_gateway WITH PASSWORD '<your-generated-password>';
CREATE DATABASE mvgc_gateway OWNER mvgc_gateway;
EOF

Your DATABASE_URL:

# Format: postgres://<user>[:<password>]@<host>[:<port>]/<database>?sslmode=<disable|require>
DATABASE_URL=postgres://mvgc_gateway:<your-generated-password>@localhost:5432/mvgc_gateway?sslmode=disable

Option C -- RHEL / Fedora / Amazon Linux (bare metal)

# 1. Install PostgreSQL 16
sudo dnf install -y postgresql16-server postgresql16

# 2. Initialise the data directory (required once after install)
sudo postgresql-16-setup --initdb

# 3. Start and enable the service
sudo systemctl enable --now postgresql-16
sudo systemctl status postgresql-16   # should show "active (running)"

# 4. Create the database user and database
sudo -u postgres psql <<'EOF'
CREATE USER mvgc_gateway WITH PASSWORD '<your-generated-password>';
CREATE DATABASE mvgc_gateway OWNER mvgc_gateway;
EOF

Your DATABASE_URL:

# Format: postgres://<user>[:<password>]@<host>[:<port>]/<database>?sslmode=<disable|require>
DATABASE_URL=postgres://mvgc_gateway:<your-generated-password>@localhost:5432/mvgc_gateway?sslmode=disable

Option D -- macOS

See the macOS deployment guide for brew install postgresql@16 end-to-end alongside the gateway install.

Option E -- Cloud managed (AWS RDS, GCP Cloud SQL, Azure)

Create a PostgreSQL 15+ instance using your cloud console or OpenTofu module, then connect as the admin user and run:

CREATE USER mvgc_gateway WITH PASSWORD '<your-generated-password>';
CREATE DATABASE mvgc_gateway OWNER mvgc_gateway;

Use the host and port from your cloud provider's connection details. Enable SSL:

# Format: postgres://<user>[:<password>]@<host>[:<port>]/<database>?sslmode=<disable|require>
DATABASE_URL=postgres://mvgc_gateway:<your-generated-password>@<cloud-host>:5432/mvgc_gateway?sslmode=require

Note sslmode=require instead of disable -- cloud managed instances require TLS.

Verify the connection (all options)

Before starting the gateway, confirm you can reach the database:

# Format: postgres://<user>[:<password>]@<host>[:<port>]/<database>?sslmode=<disable|require>
psql "postgres://mvgc_gateway:<your-generated-password>@localhost:5432/mvgc_gateway?sslmode=disable" \
  -c '\conninfo'
# Expected output: You are connected to database "mvgc_gateway" as user "mvgc_gateway" ...

If psql is not installed locally, the gateway's startup log will show the connection error clearly if the DATABASE_URL is wrong -- it will not start silently with a bad connection.

IT Setup Overview