~/work/deployment-portal
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.
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
Docker SDK → Docker CLI
- 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.
- 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.
- 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.
bcrypt / passlib 72-byte limit
- Dropped passlib and hashed passwords directly with the bcrypt library instead of going through its wrapper.
- passlib's bcrypt backend rejected some passwords with "password cannot be longer than 72 bytes."
Docker CLI flag mismatch
- Switched from docker create --detach to docker run --detach.
- docker create --detach errored with "unknown flag --detach." Small, but a real example of the CLI-wrapping approach requiring exact command shapes, not approximations.
Rollback lineage and audit logging
- 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.
- 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
- Docker SDK for Python incompatible with the host Docker daemon across environments.
- Replaced all container operations with direct Docker CLI invocations via subprocess.
- The CLI, wrapped carefully, turned out more portable and easier to debug than the official SDK.
password cannot be longer than 72 bytes
- passlib's bcrypt backend enforcing a length limit unexpectedly.
- Dropped passlib, hashed passwords directly with the bcrypt library.
- Even a wrapper around something as simple as bcrypt can introduce its own bug.
unknown flag --detach on docker create
- Incorrect assumption about which Docker CLI subcommand accepts which flags.
- Switched to docker run --detach.
- 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.