Skip to main content

​
Overview

The VidaPlus API can be easily deployed using Docker, which provides a consistent and isolated environment for running the application. This guide covers building Docker images and running containers for production deployment.

​
Prerequisites

Before you begin, ensure you have:
  • Docker installed on your machine
  • Basic familiarity with Docker commands
  • A copy of the VidaPlus API source code

​
Dockerfile Configuration

The VidaPlus API uses a Python 3.13 slim image as its base. Here’s the Dockerfile structure: 
FROM python:3.13-slim
ENV POETRY_VIRTUALENVS_CREATE=false

WORKDIR app/
COPY . .

RUN pip install poetry

RUN poetry config installer.max-workers 10
RUN poetry install --no-interaction --no-ansi --without dev

EXPOSE 8000
CMD poetry run uvicorn --host 0.0.0.0 vidaplus.app:app

​
Key Configuration Points

  • Base Image: Uses python:3.13-slim for a lightweight Python environment
  • Poetry Configuration: Disables virtual environment creation with POETRY_VIRTUALENVS_CREATE=false
  • Dependencies: Installs production dependencies only (excludes dev dependencies)
  • Port Exposure: Exposes port 8000 for the FastAPI application
  • Entry Point: Runs Uvicorn server with the FastAPI app

​
Building the Docker Image

1

Navigate to Project Directory

Open your terminal and navigate to the VidaPlus API root directory:
cd /path/to/vidaplus-api
2

Build the Image

Build the Docker image with a specific tag:
docker build -t vidaplus-api .
This command builds an image named vidaplus-api using the Dockerfile in the current directory.
3

Verify the Build

Check that the image was created successfully:
docker images | grep vidaplus-api
You should see output similar to:
vidaplus-api    latest    abc123def456    2 minutes ago    500MB

​
Running the Container

​
Basic Container Setup

To run the VidaPlus API container with basic configuration: 
docker run -d --name vidaplus-api -p 8000:8000 vidaplus-api
Flags explanation:
  • -d: Run container in detached mode (background)
  • --name vidaplus-api: Assign a name to the container
  • -p 8000:8000: Map port 8000 on host to port 8000 in container

​
Running with Environment Variables

The VidaPlus API requires environment variables for database connection and JWT authentication. Pass them using the -e flag or an environment file: 
docker run -d --name vidaplus-api \
  -p 8000:8000 \
  -e DATABASE_URL="postgresql://user:password@localhost:5432/vidaplus" \
  -e SECRET_KEY="your-secret-key-here" \
  -e ALGORITHM="HS256" \
  -e ACCESS_TOKEN_EXPIRE_MINUTES=30 \
  vidaplus-api
Create a .env file based on .env.example from the repository. The required environment variables are:
  • DATABASE_URL: PostgreSQL connection string
  • SECRET_KEY: Secret key for JWT token generation
  • ALGORITHM: JWT algorithm (typically HS256)
  • ACCESS_TOKEN_EXPIRE_MINUTES: Token expiration time in minutes

​
Accessing the API

Once the container is running, you can access:

API Endpoints

Main API at http://localhost:8000

Interactive Documentation

Swagger UI at http://localhost:8000/docs

Alternative Docs

ReDoc at http://localhost:8000/redoc

OpenAPI Schema

JSON schema at http://localhost:8000/openapi.json

​
Container Management

​
Viewing Container Logs

docker logs vidaplus-api
For continuous log streaming: 
docker logs -f vidaplus-api

​
Stopping the Container

docker stop vidaplus-api

​
Starting a Stopped Container

docker start vidaplus-api

​
Restarting the Container

docker restart vidaplus-api

​
Removing the Container

docker rm vidaplus-api
Make sure to stop the container before removing it, or use docker rm -f vidaplus-api to force removal.

​
Production Deployment Considerations

​
Database Connection

For production deployments, ensure your DATABASE_URL points to a production PostgreSQL database. If running PostgreSQL in another Docker container, use Docker networking: 
# Create a Docker network
docker network create vidaplus-network

# Run PostgreSQL container
docker run -d --name postgres \
  --network vidaplus-network \
  -e POSTGRES_PASSWORD=yourpassword \
  -e POSTGRES_DB=vidaplus \
  postgres:15

# Run VidaPlus API container
docker run -d --name vidaplus-api \
  --network vidaplus-network \
  -p 8000:8000 \
  -e DATABASE_URL="postgresql://postgres:yourpassword@postgres:5432/vidaplus" \
  -e SECRET_KEY="your-secret-key" \
  -e ALGORITHM="HS256" \
  -e ACCESS_TOKEN_EXPIRE_MINUTES=30 \
  vidaplus-api

​
Running Migrations

Before starting the API, run database migrations inside the container: 
docker exec vidaplus-api poetry run alembic upgrade head

​
Health Checks

Add health checks to your Docker run command: 
docker run -d --name vidaplus-api \
  -p 8000:8000 \
  --env-file .env \
  --health-cmd="curl -f http://localhost:8000/docs || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  vidaplus-api

​
Volume Persistence

If you need to persist data or logs, use Docker volumes: 
docker run -d --name vidaplus-api \
  -p 8000:8000 \
  --env-file .env \
  -v vidaplus-logs:/app/logs \
  vidaplus-api

​
Troubleshooting

​
Container Won’t Start

  1. Check container logs: docker logs vidaplus-api
  2. Verify environment variables are set correctly
  3. Ensure the database is accessible from the container

​
Port Already in Use

If port 8000 is already in use, map to a different host port: 
docker run -d --name vidaplus-api -p 8080:8000 vidaplus-api
Then access the API at http://localhost:8080

​
Database Connection Issues

  • Verify DATABASE_URL format: postgresql://username:password@host:port/database
  • If using Docker networks, use container names instead of localhost
  • Check that the database container is running and healthy

​
Next Steps

Database Migrations

Learn how to manage database migrations with Alembic

Testing

Run tests to ensure your deployment is working correctly

Build docs developers (and LLMs) love

Get started for freeTalk to us