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.
| Mode | What's included |
|---|---|
| Standalone | MCP server, REST server, PostgreSQL database, Nginx HTTP server |
| External Database | MCP 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.
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.
docker compose -f compose.yml -f compose.standalone.yml up -d --buildCompose 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:
CREATE ROLE postgrest_authenticator LOGIN NOINHERIT;
CREATE ROLE web_anon NOLOGIN;
GRANT web_anon TO postgrest_authenticator WITH INHERIT FALSE, SET TRUE;
\password postgrest_authenticatorAt 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.
docker compose up -d --buildFor external PostgreSQL, prefer SCRAM-SHA-256 and TLS. Do not use trust authentication on a remotely reachable database.
Verify the installation
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
- There are no default or hardcoded database passwords. You provide them in an untracked local
.envfile. - The bundled administrator password and the REST signing key use Docker Compose secrets. The REST account password is passed to its container environment in this prototype and can be visible to someone with Docker access.
- MCP never receives the bundled superuser password. User logins remain subject to the database's own permissions.
- Production deployment requires stronger secrets management, HTTPS, OAuth/OIDC, audit logging, and further verification.
Run tests
npm install
npm testGitHub Actions also checks both Compose configurations. End-to-end container testing is not yet complete.