AuthX supports two Docker deployment modes:

Standalone AuthX — runs AuthX with its required infrastructure.
DjangoPlay Full Stack — runs AuthX together with DjangoPlay, PostgreSQL, Redis, and Celery.

Docker deployment is primarily intended for local development, integration testing, and controlled self-hosted environments.

1. Deployment Modes

Standalone AuthX

Use standalone deployment when AuthX needs to run independently.

text

Docker Compose
      │
      ▼
   AuthX
      │
      ▼
 PostgreSQL
`

DjangoPlay Full Stack

Use the full-stack definition when testing the complete DjangoPlay platform.

text

                    Docker Compose
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
      AuthX          DjangoPlay        Celery
        │                │                │
        └────────────────┼────────────────┘
                         │
                 ┌───────┴───────┐
                 ▼               ▼
             PostgreSQL        Redis

AuthX and DjangoPlay remain separate application services while sharing the Compose-managed infrastructure required by the full stack.

2. Prerequisites

Install:

Docker
Docker Compose

Verify:

bash

docker --version
docker compose version

3. Standalone AuthX Deployment

3.1 Configure Environment

Create the environment file from the example:

bash

cp env.example .env

Configure the required AuthX settings in .env.

Sensitive values such as:

text

POSTGRES_PASSWORD
JWT_PRIVATE_KEY
JWT_PUBLIC_KEY
AUTHX_SERVICE_TOKEN

must not be committed to source control.

3.2 Build and Start

Start AuthX:

bash

docker compose up --build

The container initializes the database schema before starting the application.

The AuthX application is started with:

text

alembic upgrade head

uvicorn authx.main:app
    --host 0.0.0.0
    --port 8100
    --workers 2

The application is therefore available on:

text

http://localhost:8100

4. Running in Detached Mode

For background execution:

bash

docker compose up --build -d

Check running containers:

bash

docker compose ps

View AuthX logs:

bash

docker compose logs -f authx

If the Compose service has a different name, use:

bash

docker compose config --services

to display the available service names.

5. Health Check

AuthX exposes a health endpoint:

bash

curl http://localhost:8100/health

A healthy installation should return the logical result:

json

{
  "status": "ok",
  "service": "authx"
}

The health endpoint confirms that the AuthX application is responding.

It should not be treated as a complete dependency-health check unless the implementation explicitly performs those dependency checks.

6. Full DjangoPlay Stack

The repository also provides a full-stack Docker Compose definition:

bash

docker compose -f docker-compose.fullstack.yml up -d

The full-stack environment brings up the principal DjangoPlay runtime components:

text

AuthX
DjangoPlay
Celery
PostgreSQL
Redis

Conceptually:

text

                    Full Stack
                       │
       ┌───────────────┼────────────────┐
       │               │                │
       ▼               ▼                ▼
     AuthX        DjangoPlay          Celery
       │               │                │
       │               └───────┬────────┘
       │                       │
       ▼                       ▼
   PostgreSQL                Redis

This mode is useful when testing authentication, application APIs, background processing, and infrastructure together.

7. PostgreSQL Initialization

The full-stack Compose environment mounts:

text

infra/init-db.sql

The initialization script creates separate databases for the two applications:

text

authx
djangoplay

The logical database layout is:

text

PostgreSQL
   │
   ├── authx
   │     └── AuthX identity data
   │
   └── djangoplay
         └── DjangoPlay application data

This separation keeps AuthX identity persistence independent from the DjangoPlay application database even when both applications use the same PostgreSQL server.

8. Database Initialization Behaviour

PostgreSQL initialization scripts mounted into the official PostgreSQL container are normally executed when the database volume is initialized.

Therefore, changing:

text

infra/init-db.sql

does not necessarily recreate databases in an already-initialized Docker volume.

For a fresh local environment, the volume can be removed and recreated:

bash

docker compose -f docker-compose.fullstack.yml down -v

Then start the stack again:

bash

docker compose -f docker-compose.fullstack.yml up -d

Warning: removing volumes deletes the data stored in those Docker volumes. Use this only when the local data can safely be discarded.

9. Database Migrations

AuthX database migrations are handled through Alembic:

bash

alembic upgrade head

When running AuthX through its Docker deployment, the migration step is executed before the Uvicorn application process starts.

The important sequence is:

text

Container Start
      │
      ▼
Alembic Migration
      │
      ▼
Database Ready
      │
      ▼
Uvicorn
      │
      ▼
AuthX API

This prevents the application from starting against an unapplied AuthX migration state.

10. Stopping the Environment

Stop the standalone environment:

bash

docker compose down

Stop the full stack:

bash

docker compose -f docker-compose.fullstack.yml down

Stopping the containers does not normally remove persistent Docker volumes.

11. Rebuilding the Environment

After changing application code or Docker configuration:

bash

docker compose up --build

For the full stack:

bash

docker compose -f docker-compose.fullstack.yml up --build

To force recreation of containers:

bash

docker compose up --build --force-recreate

Use --force-recreate when configuration changes are not being reflected in existing containers.

12. Inspecting the Environment

List services:

bash

docker compose ps

Inspect the resolved Compose configuration:

bash

docker compose config

View all logs:

bash

docker compose logs

Follow logs:

bash

docker compose logs -f

View only AuthX logs:

bash

docker compose logs -f authx

Check the container directly:

bash

docker ps

13. Common Docker Issues

AuthX Does Not Start

Check the logs:

bash

docker compose logs authx

Look for:

Missing environment variables
Database connection failures
Invalid JWT key configuration
Migration errors
Port conflicts

Database Connection Failure

Verify that the configured database host points to the Compose service name, not localhost, when AuthX is running inside Docker.

Inside a Compose network:

text

AuthX container
      │
      │ PostgreSQL service name
      ▼
PostgreSQL container

localhost inside the AuthX container refers to the AuthX container itself, not the PostgreSQL container.

Port 8100 Already in Use

Check which process is using the port:

bash

lsof -i :8100

Stop the conflicting process or change the host-side port mapping in the Compose configuration.

The AuthX application itself continues to listen on:

text

0.0.0.0:8100

inside the container unless the deployment configuration changes it.

Database Changes Are Not Applied

Check the migration state:

bash

alembic current

Upgrade:

bash

alembic upgrade head

For a disposable local full-stack database, recreating the PostgreSQL volume is another option:

bash

docker compose -f docker-compose.fullstack.yml down -v
docker compose -f docker-compose.fullstack.yml up --build -d

14. Configuration and Secrets

Docker does not remove the requirement to protect AuthX secrets.

Do not commit:

text

.env
JWT_PRIVATE_KEY
JWT_PUBLIC_KEY
AUTHX_SERVICE_TOKEN
POSTGRES_PASSWORD

Use environment-specific secret management for shared or production environments.

The RSA private key is particularly sensitive because it controls AuthX JWT signing.

The public key may be distributed to consumers for JWT verification.

15. Docker Networking

In a Compose deployment, services communicate through the Docker network using service names.

Conceptually:

text

             Docker Network
                  │
       ┌──────────┼──────────┐
       │          │          │
       ▼          ▼          ▼
     AuthX    PostgreSQL    Redis
       │
       ▼
   DjangoPlay

Applications should use the Compose service name for container-to-container communication.

Hostnames such as:

text

localhost
127.0.0.1

refer to the current container when used from inside a container and should not normally be used to reach another Compose service.

16. Standalone vs Full Stack

Mode	Use Case
Standalone	Develop or test AuthX independently
Full Stack	Test AuthX together with DjangoPlay
Standalone	Debug AuthX authentication and identity behaviour
Full Stack	Validate DjangoPlay ↔ AuthX integration
Full Stack	Test PostgreSQL + Redis + Celery workflows

The standalone deployment is the preferred choice when only AuthX needs to be tested.

The full-stack deployment is appropriate when testing the complete DjangoPlay platform.

17. Docker Deployment Architecture

flowchart TD

    USER["Browser / API Client"]

    subgraph COMPOSE["Docker Compose"]
        AUTHX["AuthX<br/><small>Uvicorn + Alembic</small>"]
        DJANGO["DjangoPlay<br/><small>Django + Gunicorn</small>"]
        CELERY["Celery<br/><small>Background Worker</small>"]
        POSTGRES["PostgreSQL"]
        REDIS["Redis"]
    end

    USER --> AUTHX
    USER --> DJANGO

    AUTHX --> POSTGRES
    DJANGO --> POSTGRES

    DJANGO --> REDIS
    CELERY --> REDIS
    CELERY --> POSTGRES

    DJANGO -->|"Identity operations / JWT integration"| AUTHX

    classDef client fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef app fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef infra fill:#e6f1fb,stroke:#2474b5,stroke-width:2px,color:#174d7a

    class USER client
    class AUTHX,DJANGO,CELERY app
    class POSTGRES,REDIS infra

The diagram represents the full-stack deployment model. Standalone AuthX deployment uses only the services defined by the standalone Compose configuration.

18. Deployment Summary

AuthX can be deployed through Docker Compose without requiring a separate Python runtime on the host.

The standard standalone workflow is:

bash

cp env.example .env

# Configure .env

docker compose up --build

Verify:

bash

curl http://localhost:8100/health

The DjangoPlay integrated environment is started with:

bash

docker compose -f docker-compose.fullstack.yml up -d

The full-stack environment provides:

text

AuthX
DjangoPlay
PostgreSQL
Redis
Celery

Docker therefore provides a reproducible deployment boundary for local AuthX development and for testing the complete DjangoPlay platform.

AuthX — Docker Deployment

#1. Deployment Modes

#Standalone AuthX

#DjangoPlay Full Stack

2. Prerequisites

3. Standalone AuthX Deployment

#3.1 Configure Environment

#3.2 Build and Start

4. Running in Detached Mode

5. Health Check

6. Full DjangoPlay Stack

7. PostgreSQL Initialization

8. Database Initialization Behaviour

9. Database Migrations

10. Stopping the Environment

11. Rebuilding the Environment

12. Inspecting the Environment

13. Common Docker Issues

#AuthX Does Not Start

#Database Connection Failure

#Port 8100 Already in Use

#Database Changes Are Not Applied

14. Configuration and Secrets

15. Docker Networking

16. Standalone vs Full Stack

17. Docker Deployment Architecture

18. Deployment Summary

1. Deployment Modes

Standalone AuthX

DjangoPlay Full Stack

3.1 Configure Environment

3.2 Build and Start

AuthX Does Not Start

Database Connection Failure

Port 8100 Already in Use

Database Changes Are Not Applied