Boilerplate FastAPI & Dockerfile + NGINX

.gitignore

@@ -0,0 +1,222 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Certificates
+*.pem
+
+# Docker
+*compose.yml

Dockerfile

@@ -0,0 +1,35 @@
+# syntax=docker/dockerfile:1
+
+############################
+# Builder (compile wheels) #
+############################
+FROM python:3.11-slim AS builder
+ENV PIP_NO_CACHE_DIR=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential gcc libffi-dev libssl-dev libpq-dev pkg-config cargo \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /wheels
+COPY requirements.txt ./
+RUN python -m pip install --upgrade pip setuptools wheel
+# Build/download wheels for all deps
+RUN pip wheel --wheel-dir /wheels -r requirements.txt
+
+#######################
+# Runtime (slim)      #
+#######################
+
+FROM python:3.11-slim AS runtime
+RUN apt-get update && apt-get install -y --no-install-recommends libpq5 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY --from=builder /wheels /wheels
+COPY requirements.txt ./
+# Tell pip to ONLY use wheels from /wheels for the exact versions you built
+RUN python -m pip install --no-index --find-links=/wheels -r requirements.txt
+
+COPY . .
+EXPOSE 8000
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

app/api/deps.py

@@ -0,0 +1,33 @@
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer
+from jose import jwt, JWTError
+from app.core.config import settings
+from app.db.session import get_session
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.models.user import User
+from sqlalchemy import select
+
+bearer = HTTPBearer()
+
+async def get_db() -> AsyncSession:
+    async for s in get_session():
+        yield s
+
+async def get_current_user(token=Depends(bearer), db: AsyncSession = Depends(get_db)) -> User:
+    try:
+        payload = jwt.decode(token.credentials, settings.SECRET_KEY, algorithms=["HS256"])
+        email: str = payload.get("sub")
+    except JWTError:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
+    res = await db.execute(select(User).where(User.email == email))
+    user = res.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=401, detail="User not found")
+    return user
+
+def require_role(*roles: str):
+    async def _dep(user: User = Depends(get_current_user)):
+        if user.role not in roles:
+            raise HTTPException(status_code=403, detail="Insufficient role")
+        return user
+    return _dep

app/api/v1/auth.py

@@ -0,0 +1,25 @@
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from app.api.deps import get_db
+from app.core.security import create_access_token, verify_password
+from app.models.user import User
+
+router = APIRouter()
+
+class LoginIn(BaseModel):
+    email: str
+    password: str
+
+class TokenOut(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+
+@router.post("/login", response_model=TokenOut)
+async def login(data: LoginIn, db: AsyncSession = Depends(get_db)):
+    res = await db.execute(select(User).where(User.email == data.email))
+    user = res.scalar_one_or_none()
+    if not user or not user.hashed_password or not verify_password(data.password, user.hashed_password):
+        raise HTTPException(status_code=401, detail="Invalid credentials")
+    return TokenOut(access_token=create_access_token(user.email))

app/api/v1/keys.py

@@ -0,0 +1,60 @@
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, field_validator
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.api.deps import get_db, get_current_user
+from app.models.sshkey import SSHKey
+from sqlalchemy import select
+from sqlalchemy.orm import joinedload
+from datetime import datetime, timezone
+import base64
+
+router = APIRouter()
+
+ALLOWED_ALGOS = {"ssh-ed25519", "ecdsa-sha2-nistp256"}  # expand if needed
+
+class SSHKeyIn(BaseModel):
+    name: str
+    public_key: str
+    expires_at: datetime | None = None
+
+    @field_validator("public_key")
+    @classmethod
+    def validate_pubkey(cls, v: str):
+        # quick parse: "<algo> <b64> [comment]"
+        parts = v.strip().split()
+        if len(parts) < 2:
+            raise ValueError("Invalid SSH public key format")
+        algo, b64 = parts[0], parts[1]
+        if algo not in ALLOWED_ALGOS:
+            raise ValueError(f"Key algorithm not allowed: {algo}")
+        try:
+            base64.b64decode(b64)
+        except Exception:
+            raise ValueError("Public key is not valid base64")
+        return v
+
+class SSHKeyOut(BaseModel):
+    id: int
+    name: str
+    algo: str
+    public_key: str
+    expires_at: datetime | None
+    is_active: bool
+
+@router.post("/", response_model=SSHKeyOut)
+async def add_key(data: SSHKeyIn, db: AsyncSession = Depends(get_db), user=Depends(get_current_user)):
+    algo = data.public_key.split()[0]
+    key = SSHKey(user_id=user.id, name=data.name, public_key=data.public_key, algo=algo,
+                 expires_at=data.expires_at)
+    db.add(key)
+    await db.commit()
+    await db.refresh(key)
+    return SSHKeyOut(id=key.id, name=key.name, algo=key.algo, public_key=key.public_key,
+                     expires_at=key.expires_at, is_active=key.is_active)
+
+@router.get("/", response_model=list[SSHKeyOut])
+async def list_keys(db: AsyncSession = Depends(get_db), user=Depends(get_current_user)):
+    res = await db.execute(select(SSHKey).where(SSHKey.user_id == user.id))
+    rows = res.scalars().all()
+    return [SSHKeyOut(id=k.id, name=k.name, algo=k.algo, public_key=k.public_key,
+                      expires_at=k.expires_at, is_active=k.is_active) for k in rows]

app/core/config.py

@@ -0,0 +1,13 @@
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "Keywarden"
+    API_V1_STR: str = "/api/v1"
+    SECRET_KEY: str
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+    POSTGRES_DSN: str  # e.g. postgresql+asyncpg://user:pass@db:5432/keywarden
+    OIDC_ISSUER: str | None = None
+    OIDC_CLIENT_ID: str | None = None
+    OIDC_CLIENT_SECRET: str | None = None
+
+settings = Settings()

app/core/security.py

@@ -0,0 +1,17 @@
+from datetime import datetime, timedelta, timezone
+from jose import jwt
+from passlib.hash import argon2
+from app.core.config import settings
+
+ALGO = "HS256"
+
+def create_access_token(sub: str, minutes: int | None = None) -> str:
+    expire = datetime.now(tz=timezone.utc) + timedelta(minutes=minutes or settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    to_encode = {"sub": sub, "exp": expire}
+    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=ALGO)
+
+def verify_password(password: str, hashed: str) -> bool:
+    return argon2.verify(password, hashed)
+
+def hash_password(password: str) -> str:
+    return argon2.hash(password)

app/db/base.py

@@ -0,0 +1,5 @@
+from app.models.user import User
+from app.models.server import Server
+from app.models.sshkey import SSHKey
+from app.models.access_request import AccessRequest
+from app.models.audit import AuditEvent

app/db/session.py

@@ -0,0 +1,9 @@
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
+from app.core.config import settings
+
+engine = create_async_engine(settings.POSTGRES_DSN, echo=False, future=True)
+AsyncSessionLocal = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)
+
+async def get_session() -> AsyncSession:
+    async with AsyncSessionLocal() as session:
+        yield session

app/main.py

@@ -0,0 +1,12 @@
+from fastapi import FastAPI
+from app.core.config import settings
+from app.api.v1 import auth, keys
+
+app = FastAPI(title=settings.PROJECT_NAME)
+app.include_router(auth.router, prefix=f"{settings.API_V1_STR}/auth", tags=["auth"])
+app.include_router(keys.router, prefix=f"{settings.API_V1_STR}/keys", tags=["keys"])
+
+# Health endpoint (useful for docker, agent and uptime)
+@app.get("/healthz")
+def healthz():
+    return {"status": 'ok'}

app/models/access_request.py

@@ -0,0 +1,13 @@
+from sqlalchemy import ForeignKey, String, DateTime
+from sqlalchemy.orm import Mapped, mapped_column
+from datetime import datetime, timezone
+from app.models.user import Base
+
+class AccessRequest(Base):
+    __tablename__ = "access_requests"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    server_id: Mapped[int] = mapped_column(ForeignKey("servers.id", ondelete="CASCADE"))
+    status: Mapped[str] = mapped_column(String(16), default="requested")  # requested|approved|denied|expired
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    reason: Mapped[str | None] = mapped_column(String(512))

app/models/audit.py

@@ -0,0 +1,15 @@
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy import String, DateTime
+from datetime import datetime, timezone
+from app.models.user import Base
+
+class AuditEvent(Base):
+    __tablename__ = "audit_events"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    ts: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(tz=timezone.utc))
+    actor: Mapped[str] = mapped_column(String(254))     # email or system
+    action: Mapped[str] = mapped_column(String(64))     # "request.create", "key.add", etc.
+    object: Mapped[str] = mapped_column(String(64))     # "server:host123" / "user:42"
+    details: Mapped[str] = mapped_column(String(1024))  # summary (keep short)
+    prev_hash: Mapped[str | None] = mapped_column(String(128))
+    curr_hash: Mapped[str | None] = mapped_column(String(128))

app/models/server.py

@@ -0,0 +1,11 @@
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy import String, JSON, Boolean, Integer
+from app.models.user import Base
+
+class Server(Base):
+    __tablename__ = "servers"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    hostname: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    tags: Mapped[dict] = mapped_column(JSON, default=dict)  # e.g. {"env":"prod","group":"db"}
+    managed: Mapped[bool] = mapped_column(Boolean, default=True)
+    version: Mapped[int] = mapped_column(Integer, default=0)  # bump to trigger agent reconcile

app/models/sshkey.py

@@ -0,0 +1,14 @@
+from sqlalchemy import ForeignKey, String, DateTime, Boolean
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from datetime import datetime, timezone
+from app.models.user import Base
+
+class SSHKey(Base):
+    __tablename__ = "ssh_keys"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    name: Mapped[str] = mapped_column(String(80))
+    public_key: Mapped[str] = mapped_column(String(4096))
+    algo: Mapped[str] = mapped_column(String(32))
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)

app/models/user.py

@@ -0,0 +1,13 @@
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy import String, Boolean
+from app.db.session import engine  # only for Alembic discovery, not used here
+from sqlalchemy.orm import declarative_base
+Base = declarative_base()
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True, index=True)
+    email: Mapped[str] = mapped_column(String(254), unique=True, index=True)
+    hashed_password: Mapped[str | None] = mapped_column(String(255))
+    role: Mapped[str] = mapped_column(String(32), default="user")  # user|admin|auditor
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)

docker-compose.yml.example

@@ -0,0 +1,45 @@
+services:
+  nginx:
+    container_name: nginx
+    image: nginx:alpine
+    restart: unless-stopped
+    volumes:
+      - ${DOCKERDIR}/nginx/configs/nginx.conf:/etc/nginx/nginx.conf:ro
+      - ${DOCKERDIR}/nginx/configs/sites:/etc/nginx/conf.d/
+      - ${DOCKERDIR}/nginx/certs/:/certs/
+      - ${DOCKERDIR}/nginx/webdir/:/var/www/
+      - ${DOCKERDIR}/nginx/logs:/var/log/nginx/
+    ports:
+      - "443:443"
+
+  nginx-valkey:
+    image: valkey/valkey:latest
+    restart: unless-stopped
+    container_name: nginx-valkey
+    environment:
+      - ALLOW_EMPTY_PASSWORD=yes
+
+  db:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
+      POSTGRES_DB: keywarden
+      POSTGRES_USER: postgres
+    # ports: ["5432:5432"]
+    volumes: 
+      - "pgdata:/var/lib/postgresql/data"
+
+  api:
+    build: .
+    depends_on:
+      - db
+    environment:
+      - SECRET_KEY=[CREATE SECRET KEY]
+      - POSTGRES_DSN=postgresql+asyncpg://postgres:${POSTGRES_PASSWORD:-postgres}@keywarden-postgres:5432/keywarden
+      - ACCESS_TOKEN_EXPIRE_MINUTES=60
+    ports: 
+      - "8000:8000"
+    command: uvicorn app.main:app --host 0.0.0.0 --port 8000
+
+volumes:
+  pgdata:

nginx/certs/options-ssl-nginx.conf

@@ -0,0 +1,14 @@
+# This file contains important security parameters. If you modify this file
+# manually, Certbot will be unable to automatically provide future security
+# updates. Instead, Certbot will print and log an error message with a path to
+# the up-to-date file that you will need to refer to when manually updating
+# this file.
+
+ssl_session_cache shared:le_nginx_SSL:10m;
+ssl_session_timeout 1440m;
+ssl_session_tickets off;
+
+ssl_protocols TLSv1.2 TLSv1.3;
+ssl_prefer_server_ciphers off;
+
+ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384";

nginx/configs/nginx.conf

@@ -0,0 +1,42 @@
+# This file should be put under /etc/nginx/conf.d/
+# Or place as /etc/nginx/nginx.conf
+
+user  nginx;
+worker_processes  auto;
+
+error_log  /var/log/nginx/error.log warn;
+pid        /var/run/nginx.pid;
+
+events {
+    worker_connections  1024;
+}
+
+http {
+    real_ip_header X-Forwarded-For;
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+
+    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
+                      '$status $body_bytes_sent "$http_referer" '
+                      '"$http_user_agent" "$http_x_forwarded_for"';
+
+    access_log  /var/log/nginx/access.log  main;
+
+    server_tokens       off;
+
+    sendfile            on;
+    tcp_nopush          on;
+
+    keepalive_timeout   60;
+    tcp_nodelay         on;
+    client_body_timeout 15;
+
+    gzip                on;
+    gzip_vary           on;
+    gzip_min_length             1k;
+    client_max_body_size 10G;
+    proxy_request_buffering off;
+    include /etc/nginx/conf.d/*.conf;
+
+    types_hash_bucket_size 128;
+}

nginx/configs/sites/default.conf

@@ -0,0 +1,39 @@
+# Default NGINX Config
+server {
+    listen 80;
+    listen [::]:80;
+    server_name _;
+
+    return 301 https://$host$request_uri;
+}
+
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+        http2 on;
+
+    server_name _;
+
+    ssl_certificate /certs/certificate.pem;
+    ssl_certificate_key /certs/key.pem;
+    include /certs/options-ssl-nginx.conf;
+
+    client_max_body_size 50M;
+
+    location / {
+
+    }
+
+    location /api/v1/ {
+        proxy_pass  http://api:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
+        add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;
+    }
+    location /healthz {
+        proxy_pass  http://api:8000;
+    }
+}

requirements.txt

@@ -0,0 +1,13 @@
+fastapi==0.114.2
+uvicorn[standard]==0.30.6
+SQLAlchemy[asyncio]==2.0.35
+asyncpg==0.29.0
+alembic==1.13.2
+python-jose[cryptography]==3.3.0
+passlib[argon2]==1.7.4
+pydantic-settings==2.4.0
+cryptography==43.0.1
+structlog==24.4.0
+prometheus-fastapi-instrumentator==6.1.0
+httpx==0.27.2
+pytest==8.3.3