Self Hosting Revision

Self-hosting Revision allows you to deploy and manage the architecture documentation tool on your own infrastructure, giving you full control over data, security, and customization.

This deployment model is ideal for organizations with strict data governance requirements, custom infrastructure needs, or those wanting to integrate Revision deeply into their existing toolchain.

Prerequisites

Infrastructure Requirements

A self-hosted Revision deployment requires a container runtime environment that can orchestrate multiple interconnected services. The deployment can run on a single node for smaller teams or scale across multiple nodes, depending on scale and internal policies.

Specifications

• Container runtime: Docker Engine or a compatible runtime (e.g., Podman, containerd, OpenShift, Azure Container Apps, or Kubernetes).
• Compose or orchestration tool: Docker Compose (v2+) or equivalent orchestration support.
• Storage: Persistent storage volumes for database, attachments, and generated files.
• Network access: Internal network connectivity between all containers. Internet access is optional but recommended for image updates.
• PostgreSQL 14: Used as the main database. A standard Docker image or managed Postgres service can be used.
• SMTP server: Required for sending transactional emails such as password resets and invitations.
• Reverse proxy / SSL: An HTTPS endpoint for secure external access.
• Access to Revision container registry: Credentials to pull official images from ghcr.io/revision-org.

Architecture Overview

A self-hosted Revision deployment is composed of a small number of containerized services that together provide the full application stack.

Each service runs independently but communicates over the internal network defined by the container runtime or orchestrator.

Core Components

Service	Image	Description
revision-app	ghcr.io/revision-org/revision-app:latest	The main web application providing the user interface and API endpoints.
revision-worker	ghcr.io/revision-org/revision-worker:latest	Handles background jobs such as API integrations.
revision-db	postgres:14	The PostgreSQL 14 database storing all models, diagrams, attributes, and metadata.

Data Persistence

A self-hosted Revision deployment relies on persistent storage to ensure that data remains available across container restarts, upgrades, or host reboots.

Persistent volumes are used to store critical application data, database content, and generated files.

Backup Recommendations

• Database backups: Use standard PostgreSQL tools such as pg_dump or pg_basebackup.
• File storage backups: Regularly archive the attachment-data and image-data volumes.

Updates and Upgrades

Self-hosted installations of Revision can be updated by pulling the latest container images from the Revision image registry and restarting the stack.

Updates are typically backward compatible, and database migrations are applied automatically on startup.

Versioning

• Revision images are tagged with semantic versions (e.g., ghcr.io/revision-org/revision-app:1.12.3).
• The latest tag always points to the most recent stable release.
• For production environments, pin specific versions in your compose or orchestration configuration to ensure controlled rollouts.

Environment Variables

Environment variables control how each container in a self-hosted Revision setup behaves.

Most configurations can be kept as defaults, but database, mail, and internal URLs must be adjusted for your environment.

revision-app

Variable	Description	Required	Example
DATABASE_URL	Connection string for the PostgreSQL database.	✅	postgresql://postgres:postgres@revision-db:5432/postgres
SMTP_HOST	Hostname or IP of the SMTP mail server.	✅	smtp.company.local
SMTP_PORT	Port used for outgoing email (usually 25, 465, or 587).	❌	587
SMTP_USER	Username for SMTP authentication.	❌	no-reply@company.local
SMTP_PASS	Password for SMTP authentication.	❌	********
PORT	Port exposed inside the container (default 3000).	❌	3000

revision-worker

Variable	Description	Required	Example
DATABASE_URL	Connection string for the PostgreSQL database.	✅	postgresql://postgres:postgres@revision-db:5432/postgres

revision-db

Variable	Description	Required	Example
POSTGRES_USER	PostgreSQL username.	✅	postgres
POSTGRES_PASSWORD	PostgreSQL password.	✅	postgres
POSTGRES_DB	Database name (default is postgres).	❌	revision

Deployment Examples

Docker Compose

Here's a basic Docker Compose configuration for self-hosting Revision:

version: '3.8'

services:
  revision-app:
    image: ghcr.io/revision-org/revision-app:latest
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@revision-db:5432/postgres
      - SMTP_HOST=smtp.company.local
      - SMTP_PORT=587
      - SMTP_USER=no-reply@company.local
      - SMTP_PASS=your-smtp-password
    depends_on:
      - revision-db
    volumes:
      - attachment-data:/app/attachments
      - image-data:/app/images

  revision-worker:
    image: ghcr.io/revision-org/revision-worker:latest
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@revision-db:5432/postgres
    depends_on:
      - revision-db

  revision-db:
    image: postgres:14
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=revision
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:
  attachment-data:
  image-data: