Skip to main content

​
Installation Guide

This guide covers everything you need to install and configure VidaPlus API, from local development setup to production deployment with Docker.

​
Prerequisites

Before installing VidaPlus API, ensure you have the following:
  • Python: Version 3.13 or higher (specifically tested with 3.13.2)
  • Poetry: Version 2.1.2 for dependency management
  • Database: PostgreSQL (recommended) or SQLite for development
  • Docker (optional): For containerized deployment

​
Local Development Setup

​
Step 1: Install Python 3.13

VidaPlus API requires Python 3.13.2. We recommend using pyenv for Python version management: 
curl https://pyenv.run | bash

​
Step 2: Install Poetry

Poetry is the package manager used by VidaPlus API. Install version 2.1.2: 
pipx install poetry==2.1.2
pipx inject poetry poetry-plugin-shell
If you don’t have pipx installed, install it first:
python -m pip install --user pipx
python -m pipx ensurepath
Verify the installation: 
poetry --version
# Output: Poetry (version 2.1.2)

​
Step 3: Clone the Repository

Clone the VidaPlus API repository: 
git clone https://github.com/lrauane/vidaplus-api.git
cd vidaplus-api

​
Step 4: Install Dependencies

Install all project dependencies using Poetry:
1

Install production dependencies

poetry install
This installs all required packages including:
  • FastAPI (web framework)
  • SQLAlchemy (ORM with async support)
  • Pydantic Settings (configuration management)
  • Alembic (database migrations)
  • PyJWT (JWT authentication)
  • pwdlib with Argon2 (password hashing)
  • Uvicorn (ASGI server)
2

Install with development dependencies (optional)

poetry install --with dev
This includes additional tools for development:
  • pytest (testing framework)
  • pytest-cov (code coverage)
  • pytest-asyncio (async test support)
  • ruff (linting and formatting)
  • taskipy (task runner)

​
Step 5: Configure Environment Variables

Create a .env file in the project root directory with the required configuration: 
DATABASE_URL=sqlite+aiosqlite:///./database.db
SECRET_KEY=your-secret-development-key-change-this
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
Security Best Practices:
  • Never commit your .env file to version control
  • Generate a strong random secret key for production
  • Use a secure PostgreSQL database in production
  • Consider shorter token expiration times for sensitive applications

​
Generate a Secure Secret Key

Generate a cryptographically secure secret key: 
python -c "import secrets; print(secrets.token_urlsafe(32))"

​
Step 6: Database Setup

Initialize the database with Alembic migrations:
1

Run database migrations

poetry run alembic upgrade head
This creates all necessary database tables and schema.
2

Verify database connection

Check that the database file was created (for SQLite) or the tables exist in PostgreSQL.

​
Step 7: Start the Development Server

Activate the Poetry virtual environment and start the server: 
poetry shell
task run
The API will be available at:
The --reload flag enables automatic reloading when code changes. This should only be used in development.

​
Docker Installation

For production deployment or simplified setup, use Docker to containerize VidaPlus API.

​
Step 1: Install Docker

Ensure Docker is installed on your system: 
docker --version
If not installed, download from https://docs.docker.com/get-docker/

​
Step 2: Build the Docker Image

Build the VidaPlus API Docker image: 
docker build -t vidaplus-api .
This uses the Dockerfile which:
  1. Uses Python 3.13-slim base image
  2. Installs Poetry
  3. Installs production dependencies (excludes dev dependencies)
  4. Exposes port 8000
  5. Runs the application with Uvicorn

​
Step 3: Run the Container

docker run -d --name vidaplus-api -p 8000:8000 vidaplus-api

​
Step 4: Verify Container Status

Check that the container is running: 
docker ps
View container logs: 
docker logs vidaplus-api

​
Step 5: Access the API

The API is now available at http://localhost:8000 Test the connection: 
curl http://localhost:8000/docs
For a complete setup with PostgreSQL database, create a docker-compose.yml file:
docker-compose.yml
version: '3.8'

services:
  db:
    image: postgres:16-alpine
    container_name: vidaplus-db
    environment:
      POSTGRES_USER: vidaplus
      POSTGRES_PASSWORD: secure_password_here
      POSTGRES_DB: vidaplus
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U vidaplus"]
      interval: 10s
      timeout: 5s
      retries: 5

  api:
    build: .
    container_name: vidaplus-api
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql+asyncpg://vidaplus:secure_password_here@db:5432/vidaplus
      SECRET_KEY: your-secret-key-here
      ALGORITHM: HS256
      ACCESS_TOKEN_EXPIRE_MINUTES: 30
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

volumes:
  postgres_data:
Start the entire stack: 
docker-compose up -d
Stop the stack: 
docker-compose down

​
Available Task Commands

VidaPlus API uses Taskipy for common development tasks. Here are the available commands: 
task lint
# Runs ruff to check code quality

​
Database Configuration

​
SQLite (Development)

For local development, SQLite is the easiest option: 
DATABASE_URL=sqlite+aiosqlite:///./database.db
The database file will be created in the project root.

​
PostgreSQL (Production)

For production, use PostgreSQL with the async driver: 
DATABASE_URL=postgresql+asyncpg://username:password@host:5432/database_name
The asyncpg driver is required for async SQLAlchemy support in FastAPI.

​
Running Migrations

When database schema changes, run migrations: 
poetry run alembic upgrade head

​
Verification

After installation, verify everything is working:
1

Check API Health

curl http://localhost:8000/docs
You should see the Swagger UI documentation page.
2

Verify OpenAPI Schema

curl http://localhost:8000/api/v1/openapi.json
This should return the complete OpenAPI specification.
3

Test Database Connection

Try accessing any endpoint through the interactive docs at /docs.

​
Troubleshooting

  • Ensure pipx is installed and in your PATH
  • Try installing Poetry with pip: pip install poetry==2.1.2
  • Check Python version: python --version (must be 3.13+)
  • Verify DATABASE_URL format in .env file
  • For PostgreSQL, ensure the database server is running
  • Check database credentials and permissions
  • For Docker, use host.docker.internal to connect to host machine
Find and stop the process using port 8000:
lsof -i :8000
kill -9 <PID>
Or use a different port:
poetry run uvicorn vidaplus.app:app --port 8001
  • Clear Docker cache: docker builder prune
  • Ensure Dockerfile is in project root
  • Check Docker has sufficient disk space
  • Try building with no cache: docker build --no-cache -t vidaplus-api .
  • Activate Poetry shell: poetry shell
  • Reinstall dependencies: poetry install
  • Check you’re in the project root directory
  • Verify PYTHONPATH includes the project directory

​
Production Deployment Considerations

When deploying to production:
Security Checklist:
  • Use PostgreSQL instead of SQLite
  • Generate a strong, random SECRET_KEY
  • Enable HTTPS/TLS encryption
  • Set appropriate CORS policies
  • Configure firewall rules
  • Use environment-specific configuration
  • Enable logging and monitoring
  • Set up automated backups
  • Implement rate limiting
  • Use a reverse proxy (nginx/traefik)
  • Application: VidaPlus API in Docker container
  • Database: PostgreSQL with replication
  • Reverse Proxy: Nginx or Traefik
  • Process Manager: Docker Compose or Kubernetes
  • Monitoring: Prometheus + Grafana
  • Logging: ELK Stack or Cloud provider logs

​
Next Steps

Quickstart Guide

Learn how to make your first API request

API Reference

Explore all available endpoints

Authentication

Set up JWT authentication

Core Concepts

Learn about authentication and database models

Build docs developers (and LLMs) love

Get started for freeTalk to us