Skip to content
Axiomony documentation

Install Axiomony

Choose Standalone for a complete Docker stack, or External Database for MCP and REST only.

Choose a deployment mode

Axiomony now offers just two Docker setups. Both use the same .env file, and neither needs an external startup script or a separate demo stack.

ModeWhat's included
StandaloneMCP server, REST server, PostgreSQL database, Nginx HTTP server
External DatabaseMCP server and REST server, connected to your existing database

Development prototype. Services bind to localhost by default. HTTP Basic with reusable database credentials is not appropriate for a publicly accessible MCP server.

Configure the environment

Install Docker Engine and a recent Docker Compose v2 release. Clone the repository, then copy the example environment file. Node.js 22+ is only necessary if you run the source code outside Docker.

Get started
git clone https://github.com/sjoerdvanderhoorn/axiomony.git
cd axiomony
cp .env.example .env
# Open .env and enter the credentials required for your mode.

For both modes set PGDATABASE, a strong REST_AUTH_PASSWORD for the limited REST account, and a random REST_JWT_SECRET of at least 32 characters. Use distinct passwords; do not commit .env.

Mode 1 · Standalone

This mode includes all services, with persistent Docker volumes for database records and static site files. You choose the initial administrator password yourself. Add a strong POSTGRES_BOOTSTRAP_PASSWORD to .env; the initial database user is platform_admin.

Start the complete stack
docker compose -f compose.yml -f compose.standalone.yml up -d --build

Compose mounts the chosen administrator password as a secret into the database container, not into the MCP or REST containers. A one-shot initialization container creates the separate, restricted REST authenticator using REST_AUTH_PASSWORD. The signing key is provided as another secret.

The included Nginx server hosts user-created static files at http://127.0.0.1:8088/apps/.... Anyone who can reach a published URL can read its content; do not include credentials or private data in those files.

Existing volumes: changing POSTGRES_BOOTSTRAP_PASSWORD later does not rotate the password already stored inside an initialized database. Update the database role password explicitly when rotating credentials.

Mode 2 · External Database

This mode runs exactly two services: MCP and REST. Your database already exists and must accept connections from Docker. Configure PGHOST, PGPORT, PGDATABASE, PGSSL, and PGSSLMODE in .env.

Each MCP request uses the individual user's own database username and password. Axiomony does not keep a shared database administrator login in the MCP container. REST uses a separate restricted account, which must be created once by an administrator of your existing database.

In an interactive psql session with sufficient privileges, run this example on a fresh database:

Prepare the REST login
CREATE ROLE postgrest_authenticator LOGIN NOINHERIT;
CREATE ROLE web_anon NOLOGIN;
GRANT web_anon TO postgrest_authenticator WITH INHERIT FALSE, SET TRUE;
\password postgrest_authenticator

At the password prompt, enter the same value you set as REST_AUTH_PASSWORD in your own .env. If either role already exists, inspect it before changing it. The REST authenticator must not be a superuser, bypass row-level security, or receive unqualified permissions on business tables. Explicitly authorize any REST-accessible user roles as necessary.

Start MCP and REST only
docker compose up -d --build

For external PostgreSQL, prefer SCRAM-SHA-256 and TLS. Do not use trust authentication on a remotely reachable database.

Verify the installation

Local health check
curl http://127.0.0.1:3000/health
# Expected: {"status":"ok","service":"axiomony"}

The MCP endpoint is http://127.0.0.1:3000/mcp, and REST is at http://127.0.0.1:3001/. Standalone also hosts static pages on port 8088. Next: Connect an AI client.

Password and security notes

Run tests

Node.js unit tests
npm install
npm test

GitHub Actions also checks both Compose configurations. End-to-end container testing is not yet complete.