feat: dockerize app and convert to pyproject setup
- Add pyproject.toml with proper metadata and dependency groups - Create multi-stage Dockerfile for backend - Add docker-compose.yml with dev/prod profiles - Create frontend Dockerfile with nginx - Add .dockerignore for optimized builds - Update README with Docker instructions and troubleshooting - Remove requirements.txt in favor of pyproject.toml - Ensure data persistence with Docker volumes
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-11
|
||||
@@ -0,0 +1,77 @@
|
||||
## Context
|
||||
|
||||
The backup tool currently uses a flat `requirements.txt` for Python dependencies and requires manual setup (venv, pip install, npm install). There is no standardized deployment method, making it difficult to run in production or share with team members. The codebase needs modern Python packaging and containerization for reliable, repeatable deployments.
|
||||
|
||||
Current state:
|
||||
- `backend/requirements.txt` with pinned versions
|
||||
- Manual venv creation and dependency installation
|
||||
- No Dockerfile or docker-compose setup
|
||||
- Frontend served via Vite dev server in development
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Replace `requirements.txt` with a standard `pyproject.toml` with proper project metadata
|
||||
- Add multi-stage Dockerfile for the backend
|
||||
- Add `docker-compose.yml` to orchestrate backend + frontend + optional services
|
||||
- Support both development (volume mounts, hot reload) and production (optimized builds) modes
|
||||
- Maintain backward compatibility with existing manual setup
|
||||
|
||||
**Non-Goals:**
|
||||
- No changes to application code or API behavior
|
||||
- No database migration (SQLite remains file-based)
|
||||
- No Kubernetes or cloud-specific deployment configs
|
||||
- No changes to frontend build tooling
|
||||
|
||||
## Decisions
|
||||
|
||||
**1. Poetry vs setuptools for pyproject.toml**
|
||||
- **Decision**: Use setuptools with `pyproject.toml` (PEP 621)
|
||||
- **Rationale**: Simpler, no additional tool dependency. setuptools is mature and widely supported. Poetry adds complexity without clear benefit for this project size.
|
||||
- **Alternative considered**: Poetry - rejected to avoid adding a new tool dependency
|
||||
|
||||
**2. Multi-stage Dockerfile**
|
||||
- **Decision**: Use multi-stage build with separate builder and runtime stages
|
||||
- **Rationale**: Smaller final image, faster builds via layer caching. Builder stage installs build dependencies, runtime stage has only necessary files.
|
||||
- **Alternative considered**: Single-stage - rejected due to larger image size
|
||||
|
||||
**3. Backend-only container vs full-stack**
|
||||
- **Decision**: Provide both options via docker-compose profiles
|
||||
- **Rationale**: Default `docker-compose up` runs full stack. Users can run `docker-compose --profile dev up` for development with hot reload.
|
||||
- **Alternative considered**: Separate frontend container - included as option but not default
|
||||
|
||||
**4. Base image choice**
|
||||
- **Decision**: `python:3.14-slim` for runtime, `python:3.14` for builder
|
||||
- **Rationale**: Slim reduces attack surface and image size. Full image in builder for compiling native extensions if needed.
|
||||
- **Alternative considered**: Alpine - rejected due to musl libc compatibility issues with some Python packages
|
||||
|
||||
**5. Frontend serving in Docker**
|
||||
- **Decision**: Build frontend in Docker and serve via backend static files in production
|
||||
- **Rationale**: Single container to deploy. In development, use Vite dev server with proxy.
|
||||
- **Alternative considered**: Separate nginx container - rejected to keep deployment simple
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Risk] Python 3.14 compatibility**: Some dependencies may not have pre-built wheels for Python 3.14
|
||||
- **Mitigation**: Use slim image, test build early, pin compatible versions
|
||||
|
||||
- **[Risk] Docker image size**: Including Node.js for frontend build increases image size
|
||||
- **Mitigation**: Multi-stage build ensures Node.js tooling is not in final image
|
||||
|
||||
- **[Risk] File permissions with SQLite**: Container user may not have write access to SQLite DB file
|
||||
- **Mitigation**: Create volume for data directory, set proper user/permissions in Dockerfile
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Create `pyproject.toml` with all dependencies from `requirements.txt`
|
||||
2. Create Dockerfile and docker-compose.yml
|
||||
3. Test build locally with `docker compose up`
|
||||
4. Verify all tests pass in container
|
||||
5. Update README with Docker instructions
|
||||
6. Keep `requirements.txt` temporarily, mark as deprecated
|
||||
7. After validation, remove `requirements.txt`
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should we add a healthcheck endpoint to docker-compose?
|
||||
- Do we need docker-compose override files for different environments?
|
||||
@@ -0,0 +1,29 @@
|
||||
## Why
|
||||
|
||||
The current backup tool uses a simple `requirements.txt` for dependency management and lacks containerization. This makes deployment inconsistent across environments and complicates dependency resolution. Converting to a proper `pyproject.toml` setup and adding Docker support will provide reproducible builds, standardized packaging, and one-command deployment for users.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **Convert backend to pyproject.toml**: Replace `requirements.txt` with a modern `pyproject.toml` including project metadata, dependencies, build system, and optional dev/test dependencies
|
||||
- **Add Dockerfile**: Multi-stage Docker build for the Python backend with proper layer caching
|
||||
- **Add docker-compose.yml**: Orchestrate backend + frontend services with volume mounts and environment configuration
|
||||
- **Add .dockerignore**: Optimize build context and exclude unnecessary files
|
||||
- **Update README**: Add Docker deployment instructions
|
||||
- **Frontend containerization (optional)**: Dockerfile for production frontend build served via nginx or integrated into backend static serving
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `docker-deployment`: Container-based deployment with Docker and docker-compose for consistent environments
|
||||
- `python-packaging`: Modern Python packaging with pyproject.toml, proper dependency groups, and build tooling
|
||||
|
||||
### Modified Capabilities
|
||||
- None (this is a build/deployment improvement, no spec-level behavior changes)
|
||||
|
||||
## Impact
|
||||
|
||||
- **Build system**: Replaces `requirements.txt` with `pyproject.toml` (standard modern Python practice)
|
||||
- **Deployment**: New Docker-based deployment path alongside existing manual setup
|
||||
- **CI/CD**: Enables standardized container builds for CI pipelines
|
||||
- **Developer experience**: `docker compose up` to start full stack instead of manual venv + npm setup
|
||||
- **No API changes**: All existing endpoints and functionality remain unchanged
|
||||
@@ -0,0 +1,42 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Docker image builds successfully
|
||||
The Docker image SHALL build without errors from the project root using `docker build`.
|
||||
|
||||
#### Scenario: Build from project root
|
||||
- **WHEN** developer runs `docker build -t backup-tool .`
|
||||
- **THEN** the image builds successfully with all dependencies installed
|
||||
|
||||
### Requirement: Docker Compose orchestrates full stack
|
||||
The `docker-compose.yml` SHALL start both backend and frontend services with a single command.
|
||||
|
||||
#### Scenario: Start full stack
|
||||
- **WHEN** developer runs `docker compose up`
|
||||
- **THEN** backend API is accessible on port 8000
|
||||
- **AND** frontend is accessible on port 3000
|
||||
- **AND** services can communicate with each other
|
||||
|
||||
### Requirement: Development mode supports hot reload
|
||||
The Docker setup SHALL support development mode with file watching and automatic reloading.
|
||||
|
||||
#### Scenario: Backend code changes trigger reload
|
||||
- **WHEN** developer modifies a Python file in development mode
|
||||
- **THEN** the backend service restarts automatically
|
||||
- **AND** changes are reflected without manual container rebuild
|
||||
|
||||
### Requirement: Production mode uses optimized build
|
||||
The production Docker setup SHALL use multi-stage builds and serve static files efficiently.
|
||||
|
||||
#### Scenario: Production deployment
|
||||
- **WHEN** developer runs `docker compose -f docker-compose.yml up` in production configuration
|
||||
- **THEN** frontend assets are built and served by the backend
|
||||
- **AND** no development servers are running
|
||||
- **AND** image size is minimized
|
||||
|
||||
### Requirement: Data persistence across restarts
|
||||
The Docker setup SHALL preserve SQLite database and backup files across container restarts.
|
||||
|
||||
#### Scenario: Container restart preserves data
|
||||
- **WHEN** docker containers are stopped and restarted
|
||||
- **THEN** all existing backups and job history are preserved
|
||||
- **AND** no data loss occurs
|
||||
@@ -0,0 +1,32 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: pyproject.toml replaces requirements.txt
|
||||
The project SHALL use `pyproject.toml` as the primary dependency and build configuration file.
|
||||
|
||||
#### Scenario: Install from pyproject.toml
|
||||
- **WHEN** developer runs `pip install -e .`
|
||||
- **THEN** all runtime dependencies are installed correctly
|
||||
- **AND** the package is installed in editable mode
|
||||
|
||||
### Requirement: Dependencies are properly declared
|
||||
The `pyproject.toml` SHALL declare all runtime, development, and optional dependencies in appropriate groups.
|
||||
|
||||
#### Scenario: Install with dev dependencies
|
||||
- **WHEN** developer runs `pip install -e ".[dev]"`
|
||||
- **THEN** testing tools (pytest, pytest-asyncio) are installed
|
||||
- **AND** development tools are available
|
||||
|
||||
### Requirement: Package metadata is complete
|
||||
The `pyproject.toml` SHALL include project metadata such as name, version, description, authors, and license.
|
||||
|
||||
#### Scenario: Package info is accessible
|
||||
- **WHEN** user queries package metadata via `pip show backup-tool`
|
||||
- **THEN** name, version, description, and author information are displayed
|
||||
|
||||
### Requirement: Console scripts are defined
|
||||
The `pyproject.toml` SHALL define console entry points for running the application.
|
||||
|
||||
#### Scenario: Run via CLI command
|
||||
- **WHEN** user runs `backup-tool` or `uvicorn backup_tool.main:app`
|
||||
- **THEN** the application starts successfully
|
||||
- **AND** the console script is properly registered
|
||||
@@ -0,0 +1,32 @@
|
||||
## 1. Python Packaging (pyproject.toml)
|
||||
|
||||
- [x] 1.1 Create `backend/pyproject.toml` with project metadata, dependencies, and build system
|
||||
- [x] 1.2 Migrate all dependencies from `requirements.txt` to `pyproject.toml`
|
||||
- [x] 1.3 Add optional dependency groups: `[dev]` for pytest, `[prod]` for gunicorn
|
||||
- [x] 1.4 Add console script entry point for `backup-tool` CLI
|
||||
- [x] 1.5 Test `pip install -e .` works correctly
|
||||
- [x] 1.6 Remove `backend/requirements.txt` or mark as deprecated
|
||||
|
||||
## 2. Docker Configuration
|
||||
|
||||
- [x] 2.1 Create `.dockerignore` to optimize build context
|
||||
- [x] 2.2 Create `backend/Dockerfile` with multi-stage build (builder + runtime)
|
||||
- [x] 2.3 Create `docker-compose.yml` for full stack orchestration
|
||||
- [x] 2.4 Add docker-compose profiles for dev (hot reload) and prod modes
|
||||
- [x] 2.5 Ensure SQLite database and backups persist across container restarts
|
||||
|
||||
## 3. Integration and Testing
|
||||
|
||||
- [x] 3.1 Test Docker image builds successfully from project root
|
||||
- [x] 3.2 Test `docker compose up` starts both backend and frontend
|
||||
- [x] 3.3 Verify backend hot reload works in development mode
|
||||
- [x] 3.4 Verify production mode serves static frontend files
|
||||
- [x] 3.5 Run existing test suite inside Docker container
|
||||
- [x] 3.6 Test data persistence: create backup, restart containers, verify data exists
|
||||
|
||||
## 4. Documentation
|
||||
|
||||
- [x] 4.1 Update `README.md` with Docker installation instructions
|
||||
- [x] 4.2 Document environment variables for Docker configuration
|
||||
- [x] 4.3 Add troubleshooting section for common Docker issues
|
||||
- [x] 4.4 Document both manual and Docker deployment paths
|
||||
Reference in New Issue
Block a user