Coolify Deployment

import { Aside, Steps } from ‘@astrojs/starlight/components’;

Orimora uses independent Coolify services with separate subdomains. Each can be deployed separately without affecting the others.

orimora.com          → orimora-app    (SvelteKit, Docker Compose)
docs.orimora.com     → orimora-docs   (Starlight, Dockerfile + Nginx)
(planned) marketing  → orimora-marketing (Astro static)

Routing and TLS are handled by Traefik (built into Coolify). No additional proxy container needed.

The full configuration reference including all UUIDs and env vars is in [`deploy/coolify-traefik.md`](https://github.com/defcon1702/orimora/blob/main/deploy/coolify-traefik.md) in the repository.

Architecture

Service	Domain	Build	Port
orimora-app	orimora.com	Docker Compose (docker-compose.yaml)	3000
orimora-docs	docs.orimora.com	Dockerfile (Astro build + Nginx)	80
orimora-db	(internal)	PostgreSQL 16 Alpine	5432
orimora-redis	(internal)	Redis 7 Alpine	6379

Use the **Docker Compose** build pack for orimora-app, not "Dockerfile". The plain Dockerfile pack injects env vars only as `--build-arg` which are not available at runtime. The Docker Compose pack reads `${VAR}` references from the compose file and properly injects them as runtime environment variables.

Setup

1. Create the Coolify project — name it “Orimora” with a “production” environment.

2. Create databases — PostgreSQL 16 (orimora-db) and Redis 7 (orimora-redis) inside the project. Note the internal connection URLs that Coolify generates (format: postgres://user:pass@<uuid>:5432/db).

3. Create the app service — GitHub source, repo defcon1702/orimora, branch main. Change the build pack from the default to “Docker Compose”. The default Docker Compose Location (/docker-compose.yaml) matches the file in the repo — no change needed.

4. Assign the domain — after Coolify loads the compose file, it shows the orimora service. Assign https://orimora.com to it.

5. Fill in environment variables — Coolify automatically detects all ${VAR} references from the compose file and shows them in the UI. Required variables (marked with :?) appear with a red border. Fill in at minimum: DATABASE_URL, REDIS_URL (using internal Coolify URLs), SESSION_SECRET, MAGIC_LINK_SECRET, APP_URL. Optional: SMTP settings, OAuth, ALLOW_REGISTRATION=false.

6. Create the docs service — same repo, branch main, build pack “Dockerfile”. Set Base Directory to /docs, domain to https://docs.orimora.com, port 80.

7. Enable Basic Auth (optional) — on orimora-app under General → HTTP Basic Auth. This puts a password prompt in front of the entire app until public launch.

8. Deploy — trigger a deploy for each service. Migrations run automatically on container startup.

DNS Configuration

Record	Type	Value
orimora.com	A	Your server IP
docs.orimora.com	A	Your server IP

A wildcard record (*.orimora.com) simplifies adding future subdomains.

Database Migrations

Migrations run automatically on container startup via docker-entrypoint.sh using a custom migration runner (run-migrations.mjs). No manual step is needed for initial setup or upgrades.

The runner applies each migration in its own transaction. If a migration fails, it prints the PostgreSQL error code and details. Previously applied migrations are preserved.

If you need to run migrations manually (e.g. debugging), enter the container terminal in Coolify and run:

node run-migrations.mjs

Known Pitfalls

**Duplicate environment variables:** Coolify auto-creates env vars from `${VAR}` references in the compose file. If you also create them manually, you get duplicates. After initial setup, check the env var list in Coolify and delete any empty duplicates.

**Database hostname = UUID:** Coolify-managed databases use their UUID as the Docker hostname (e.g. `atjf5bym...`). If you delete and recreate a database, the UUID changes — update `DATABASE_URL` in the app's env vars accordingly.

**Network access:** The app must join the `coolify` external network (defined in `docker-compose.yaml`) to reach Coolify-managed PostgreSQL and Redis instances. Without this, you'll get `EAI_AGAIN` DNS errors or connection timeouts.

Maintenance Mode (Basic Auth)

Coolify has built-in HTTP Basic Auth support:

1. Go to the app service → General → scroll to “HTTP Basic Auth”
2. Enable and set username/password
3. Save and redeploy

This blocks all unauthenticated access at the Traefik level — no code changes needed.

Watch Paths (Optional)

To prevent unnecessary rebuilds when only one service changed:

• orimora-app: src/, package.json, Dockerfile, svelte.config.js
• orimora-docs: docs/

Set these under each app’s General → Watch Paths in Coolify.

orimora.de Redirect

Add these Traefik labels to the orimora-app service (or create a minimal redirect service):

traefik.http.routers.orimora-de.rule=Host(`orimora.de`) || Host(`www.orimora.de`)
traefik.http.routers.orimora-de.entrypoints=https
traefik.http.routers.orimora-de.tls.certresolver=letsencrypt
traefik.http.middlewares.redirect-de.redirectregex.regex=^https://(?:www\.)?orimora\.de(.*)
traefik.http.middlewares.redirect-de.redirectregex.replacement=https://orimora.com${1}
traefik.http.middlewares.redirect-de.redirectregex.permanent=true
traefik.http.routers.orimora-de.middlewares=redirect-de

Registration Gate

Set ALLOW_REGISTRATION=false in Coolify to prevent new users from signing up via Magic Link or OAuth. The first user (admin setup) and invited users are always allowed. Change this in Coolify’s environment variables — no code change needed.

MCP Server (HTTP)

Once deployed, you can enable the MCP HTTP endpoint per team in Settings → Developers → MCP Server (HTTP). External tools like Cursor or Claude Desktop can then access your knowledge base at https://orimora.com/api/mcp using API key authentication. See the MCP guide for client configuration.

Further Reading

• MCP & AI integrations — stdio + HTTP MCP setup
• Deployment — Docker Compose for self-hosting
• Configuration — all environment variables