Skip to content
AnglinAI Docs

Docker Self-Hosted Product - Implementation Plan

Goal

Offer a supported Docker-based self-hosted deployment so customers can run the Accessible stack inside their own infrastructure without adopting our hosted SaaS environment.

Relationship To Existing Docs

This implementation plan complements:

  • docs/admin/on-prem-deployment.md

That document describes a broad on-prem strategy. This document narrows it into the concrete work needed to ship a supportable Docker-based product.

Product Promise

A customer should be able to:

  • obtain our container images
  • configure required secrets and environment values
  • start the stack with a supported compose package or installer
  • operate, update, and troubleshoot the system without custom engineering from us

Phase 1 should ship one supported self-hosted package:

  • Docker Compose based
  • Linux x86_64
  • one-node deployment
  • packaged reverse proxy
  • packaged database, storage, queue, API, workers, and monitoring

Kubernetes and VM appliance support can stay future scope.

Main Workstreams

  1. Container packaging
  2. Install and configuration experience
  3. Runtime operations
  4. Secrets management
  5. Upgrade and support model

Technical Plan

Phase 1 - Freeze the Self-Hosted Architecture

Decide the first supported bundle and do not over-generalize.

Recommended services:

  • reverse proxy
  • frontend
  • API
  • worker
  • PostgreSQL
  • MinIO
  • Redis
  • optional monitoring stack

Questions to resolve:

  • do we bundle auth locally or require external auth
  • do we bundle local AI components or require external AI providers
  • do we separate community/dev compose from supported customer compose

Phase 2 - Produce Supportable Images

Every service needs a production-grade image with:

  • pinned base image
  • health check
  • predictable startup command
  • non-root user where practical
  • documented environment variables

We also need a release strategy:

  • semantic version tags
  • signed image manifests if possible
  • image registry policy

Phase 3 - Build the Installer Experience

Customers should not need to hand-edit raw compose files beyond a small config surface.

Recommended artifacts:

  • docker-compose.customer.yml
  • .env.customer.example
  • install script
  • preflight checker for ports, disk, memory, and Docker version

Optional but valuable:

  • management CLI for init, start, stop, upgrade, backup, restore

Phase 4 - Secrets and Configuration

Decide how self-hosted customers provide:

  • app secrets
  • auth secrets
  • SMTP or email config if needed
  • AI provider keys
  • license token

Recommended defaults:

  • secrets mounted from files or Docker secrets when available
  • non-secret config via env file

We should avoid putting raw secrets directly in compose checked into source control.

Phase 5 - Persistent Data Model

Define volumes and backup expectations for:

  • PostgreSQL data
  • MinIO object storage
  • Redis persistence if needed
  • logs and monitoring retention

Need documented backup and restore commands before GA.

Phase 6 - Upgrade Strategy

Self-hosted products fail when upgrades are vague.

We need a defined upgrade path:

  • version compatibility matrix
  • migration ordering
  • image pull and restart process
  • rollback procedure

If the management CLI exists, this becomes:

  • accessible-server upgrade
  • accessible-server rollback

Phase 7 - Supportability

We need operator-facing commands or tooling for:

  • health checks
  • logs
  • disk usage
  • queue backlog
  • storage health
  • provider health

We also need a diagnostic bundle export that excludes document content but includes:

  • service versions
  • env shape with secrets redacted
  • container health
  • recent logs

Phase 8 - Documentation

Required docs:

  • system requirements
  • installation
  • first login / bootstrap admin
  • AI provider setup
  • storage locations and backups
  • upgrades and rollback
  • troubleshooting guide

MVP Constraints

To keep scope realistic, MVP should require:

  • customer-provided AI provider keys
  • a Linux server with Docker Compose
  • one supported topology
  • no multi-node clustering

Deliverables

  • production Docker images for the full supported stack
  • supported customer compose package
  • example env and secret templates
  • install and upgrade documentation
  • operator troubleshooting guide

Acceptance Criteria

  • A clean Linux host can install and run the stack using only documented steps.
  • The stack survives restart and preserves data correctly.
  • Upgrades and rollbacks work on a test environment.
  • Support can request a redacted diagnostic bundle without accessing customer content.

Estimated Effort

  • image hardening and packaging: 4-6 days
  • installer/config experience: 3-5 days
  • operations and backup tooling: 4-6 days
  • docs and QA: 3-5 days
  • Total MVP: 14-22 days