Skip to content

~/work/deployment-portal

System 02 of 03 · Internal tooling

Self-Service Deployment Portal

An internal dashboard for deploying Dockerized applications without SSH access — register a version, click deploy, and roll back safely if it fails.

FastAPI · Python · PostgreSQL · SQLAlchemy · Alembic · JWT · bcrypt · Docker · Docker Compose

Problem

A common small-team deployment pattern is SSHing into a server, pulling the latest code, and running docker build / docker run by hand. It works until it doesn't: mistakes happen under manual steps, everyone needs shared server access, there's no record of who deployed what or when, and rolling back means remembering the previous image tag correctly under pressure. This platform replaces that with a web dashboard: register an application, register a Docker image version, click deploy — no SSH access required for the person deploying.

Architecture

A FastAPI backend is the orchestration layer for everything: authentication, the application/version registry, deployment execution, and audit logging. PostgreSQL is the source of truth for deployment history. The backend never touches containers directly — every container operation is delegated to the Docker CLI, invoked through a wrapper the backend calls as a background task so the API responds immediately while the deployment runs.

Fig. 01: System flow

Architecture diagram with 7 layers. Client: Developer (JWT session). This connects to Interface: Web Dashboard. This connects to Orchestration: FastAPI Backend. FastAPI Backend also connects to PostgreSQL (users, apps, versions, deployments, logs). This connects to Execution: Background Task. This connects to Container control: Docker CLI (subprocess). This connects to Runtime: Docker Daemon. This connects to Result: Application container.

Decisions

01

Docker SDK → Docker CLI

Decision
Every container operation — pull, stop, remove, run, inspect — was rewritten to invoke the Docker CLI directly through a subprocess wrapper instead of the official Docker SDK.
Reason
The Docker SDK for Python (docker.from_env()) threw "Not supported URL scheme http+docker" inconsistently across environments during testing, traced to an incompatibility between the SDK and the host Docker daemon, not a bug in the application code calling it.
Tradeoff
This is less elegant than SDK calls and requires the Docker binary to be present wherever the API runs — accepted in exchange for reliability and much easier debugging across different Docker versions.
02

bcrypt / passlib 72-byte limit

Decision
Dropped passlib and hashed passwords directly with the bcrypt library instead of going through its wrapper.
Reason
passlib's bcrypt backend rejected some passwords with "password cannot be longer than 72 bytes."
03

Docker CLI flag mismatch

Decision
Switched from docker create --detach to docker run --detach.
Reason
docker create --detach errored with "unknown flag --detach." Small, but a real example of the CLI-wrapping approach requiring exact command shapes, not approximations.
04

Rollback lineage and audit logging

Decision
Deployments maintain a relationship to the deployment they replaced, and a separate deployment-log model records each step of a deployment — image pull, container stop, container removal, container start, and any error.
Reason
This is what makes rollback traceable instead of re-running the old image and hoping, and gives visibility into what actually happened during a failed deployment. Both are built and working rather than planned.

Deployment

Docker Compose runs the API and PostgreSQL as two services. Schema changes go through Alembic migrations, run explicitly (alembic upgrade head) rather than automatically on boot.

Constraints

  • Single-host deployments — no Kubernetes, no multi-host orchestration.
  • No role-based access control yet — every authenticated user has the same capabilities. I noted this as a known gap in the project's own docs.
  • CI/CD integration and health-check-based auto-rollback are listed as in progress in the project's own roadmap, not finished.

What broke

Not supported URL scheme http+docker

Cause
Docker SDK for Python incompatible with the host Docker daemon across environments.
Fix
Replaced all container operations with direct Docker CLI invocations via subprocess.
Lesson
The CLI, wrapped carefully, turned out more portable and easier to debug than the official SDK.

password cannot be longer than 72 bytes

Cause
passlib's bcrypt backend enforcing a length limit unexpectedly.
Fix
Dropped passlib, hashed passwords directly with the bcrypt library.
Lesson
Even a wrapper around something as simple as bcrypt can introduce its own bug.

unknown flag --detach on docker create

Cause
Incorrect assumption about which Docker CLI subcommand accepts which flags.
Fix
Switched to docker run --detach.
Lesson
CLI-wrapping needs exact command shapes. Nothing catches a wrong flag before runtime.

Result

Works as an internal tool: registering an application, registering a version, deploying it, and rolling it back all happen through the dashboard, with every step logged. I've built and tested it myself, but it hasn't been used by a team yet.

Lessons

The Docker SDK failure is the clearest lesson here: the official SDK was not the safer choice. The CLI, wrapped carefully through subprocess calls, turned out more portable across Docker versions and easier to debug when something went wrong. The gaps are still gaps, and I have kept them in the write-up: no RBAC, and CI/CD is still in progress.