Plex Playlist Project

A full-stack application for managing Plex playlists with a FastAPI backend and Vue.js frontend.

Architecture

• Backend: Python 3.14 + FastAPI + uv + ruff
• Frontend: TypeScript + Vue.js + Vite
• Database: PostgreSQL 16
• Containerization: Docker + Docker Compose

Development Setup

Prerequisites

• Docker and Docker Compose
• Git
• pre-commit (for development)

Code Quality Tools

This project uses comprehensive linting and formatting:

Backend (Python):

• ruff - Fast Python linter and formatter
• pyright - Type checking
• pydoclint - Docstring linting (Google style)

Frontend (TypeScript/Vue):

• eslint - Linting with Vue and TypeScript support
• prettier - Code formatting
• vue-tsc - Vue TypeScript checking
• eslint-plugin-tsdoc - TSDoc documentation linting

Task Runner:

• poethepoet - Unified task runner for development workflows

General:

• pre-commit - Git hooks for automated quality checks
• TOML formatting and validation

Unified Development with Poe

This project uses Poe the Poet for streamlined development:

# Complete setup (installs deps, starts dev environment)
poe setup

# Code quality (format, lint, type-check all code)
poe ci-quick

# Run all tests
poe test-all

# See all available tasks
poe --help

Manual Setup (Alternative)

pip install pre-commit
pre-commit install

Quick Start

1. Clone the repository

2. Unified Development (Recommended):

   # Complete setup and start development environment
   poe setup
   
   # Or manually:
   cd backend
   pip install -e .
   poe dev-env-start
   

3. Traditional Setup:

   # Backend development
   cd backend
   pip install -e .
   
   # Frontend development
   cd frontend
   npm install
   npm run dev
   

4. Docker Development:

   # Using Poe (recommended)
   poe docker-dev-up
   
   # Or directly
   docker compose -f compose.dev.yml up --build
   

5. Production Build:

   poe docker-prod-up
   # Or: docker compose up --build
   

Running in Production Mode

docker compose up --build -d

This will start:

• PostgreSQL database on port 5432
• FastAPI backend on port 8000
• Vue.js frontend on port 80

Project Structure

plex-playlist/
├── backend/                 # FastAPI backend
├── frontend/               # Vue.js frontend
│   └── nginx.conf          # Nginx configuration
├── Dockerfile.backend      # Backend Docker image
├── Dockerfile.frontend     # Frontend Docker image
├── compose.yml             # Production Docker Compose
├── compose.dev.yml         # Development Docker Compose override
└── README.md

CI Operations

For Gitea Actions runner image mirror maintenance, use:

• source scripts/gitea-actions/repair_runner_mirror.xsh
• source scripts/gitea-actions/check_runner_images.xsh
• source scripts/gitea-actions/collect_runner_diagnostics.xsh [since] [trace_id]

For full troubleshooting context, see docs/GITEA_ACTIONS_TROUBLESHOOTING.md.

Environment Variables

Backend

• DATABASE_URL: PostgreSQL connection string
• ENVIRONMENT: development or production
• RELOAD: Enable uvicorn auto-reload (development only)

Frontend

• NODE_ENV: development or production

Database

The PostgreSQL database is configured with:

• Database: plex_playlist
• User: plex_user
• Password: plex_password

Development Workflow

1. Make changes to your code
2. The development containers will automatically reload:
   • Backend: uvicorn with --reload flag
   • Frontend: Vite dev server with hot module replacement

API Documentation

When running, the FastAPI automatic documentation is available at:

• Development: http://localhost:8001/docs
• Production: http://localhost:8000/docs

---

Manual Setup (if not using Docker)

Backend Setup (FastAPI, Python 3.14, uv, ruff, pyright)

1. Create and activate the uv virtual environment

cd backend
uv venv .venv
source .venv/bin/activate

2. Install dependencies

uv sync --all-groups

3. Install dev tools

uv run poe format
uv run poe lint
uv run poe test

4. Project structure

• src/backend/ - FastAPI application code
• tests/ - Test suite
• pyrightconfig.json - Pyright type checking config
• pyproject.toml - Ruff, pytest, and task configuration

5. Run the development server

uv run uvicorn backend.main:app --reload --app-dir src

---

Frontend Setup (Vue 3, Vite, TypeScript)

1. Create the project

cd frontend
npm create vite@latest . -- --template vue-ts
npm install

2. Recommended: Enable strictest TypeScript settings

Edit tsconfig.json and set:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  }
}

3. Run the frontend

npm run dev

---

Documentation

Development & Workflow

• Development Environment Setup - Comprehensive guide for setting up your development environment, git workflow, pre-commit hooks, manual tool usage, and CI/CD pipeline understanding
• Poe Task Reference - Complete guide to unified development tasks and workflows using Poe the Poet

Architecture & CI/CD

• CI/CD Multi-stage Build - Docker multi-stage build strategy, architecture decisions, and performance optimizations
• CI/CD Troubleshooting Guide - Comprehensive troubleshooting, optimization decisions, and performance monitoring for Docker builds and E2E testing
• CI/CD Success Summary - Complete validation results and performance metrics for the optimized pipeline

Dependency Management & Automation

• Renovate Bot Setup - Automated dependency updates with Renovate for Python, Node.js, and Docker dependencies
• Gitea API Token Setup - Step-by-step guide for creating organization API tokens with proper permissions

Operations & Troubleshooting

• Gitea Actions Troubleshooting - Solutions for CI/CD pipeline issues, including the critical "jobs waiting forever" problem
• Secure Docker CI/CD - Security considerations and setup for Docker-based CI/CD pipelines

See the backend/ and frontend/ folders for more details.