---
since: 1.1.1
---
# AuthX — Docker Deployment
This document describes how to run AuthX using Docker Compose.
AuthX supports two Docker deployment modes:
1. **Standalone AuthX** — runs AuthX with its required infrastructure.
2. **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
```mermaid
flowchart TD
USER["Browser / API Client"]
subgraph COMPOSE["Docker Compose"]
AUTHX["AuthX
Uvicorn + Alembic"]
DJANGO["DjangoPlay
Django + Gunicorn"]
CELERY["Celery
Background Worker"]
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.