From 3965aca42fece4cba20d6561f2c7f78fa94e5fea Mon Sep 17 00:00:00 2001 From: Alex Blank Date: Mon, 27 Jul 2026 15:24:01 +0200 Subject: [PATCH] docs: refresh README --- README.md | 214 +++++++++++++++--------------------------------------- 1 file changed, 57 insertions(+), 157 deletions(-) diff --git a/README.md b/README.md index bb2e30d..de349a7 100644 --- a/README.md +++ b/README.md @@ -1,81 +1,53 @@ # Backup Tool -A modern backup management application with a FastAPI backend and React frontend. +Backup Tool is a FastAPI and React application for managing local, SSH/SFTP, PostgreSQL, and MySQL backup sources. It provides backup jobs and executions, scheduling, retention policies, a web dashboard, and a REST API. -## Features +## Status and limitations -- **Multiple Source Types**: Local filesystem, SSH/SFTP, and database (PostgreSQL, MySQL) -- **Backup Strategies**: Full and incremental backups -- **Scheduled Backups**: Cron-based scheduling with APScheduler -- **Retention Policies**: Count-based and days-based backup retention -- **Web Dashboard**: React-based UI for managing backups -- **REST API**: Full REST API for programmatic access +The backend package is versioned `0.1.0` and classified as beta. Runtime verification is outside this README; review the configuration and test commands below before using the application for production backups. -## Architecture +The Compose configuration sets `BACKUP_STORAGE_PATH=/app/backups`, but the current Python application does not read that environment variable. The `/app/backups` volume is still mounted by Compose; the application's effective use of that path is not verified here. -``` -backup-tool/ -├── backend/ # FastAPI backend -│ ├── app/ # FastAPI application -│ │ ├── routers/ # API endpoints -│ │ ├── models.py # SQLAlchemy models -│ │ ├── schemas.py # Pydantic schemas -│ │ └── main.py # Application entry point -│ ├── backup/ # Backup engine -│ │ ├── adapters/ # Source adapters (local, SSH, database) -│ │ ├── engine.py # Backup execution engine -│ │ ├── scheduler.py # Job scheduler -│ │ └── retention.py # Retention policies -│ └── requirements.txt # Python dependencies -├── frontend/ # React frontend -│ ├── src/ # Source code -│ └── package.json # Node dependencies -└── docs/ # Documentation -``` +## Prerequisites -## Quick Start +- Docker with Docker Compose for the containerized setup. +- Python 3.11 or newer for manual backend development. +- Node.js for manual frontend development. The development Compose service uses Node 20 Alpine; no standalone Node version is declared by the frontend package. -### Option 1: Docker (Recommended) +## Run with Docker Compose -The easiest way to run the backup tool is using Docker Compose: +From the repository root: ```bash -# Start the backend +# Backend only docker compose up -d -# Start with frontend (production) +# Backend plus the production frontend docker compose --profile prod up -d -# Start with frontend (development with hot reload) +# Backend plus the Vite development frontend docker compose --profile dev up -d ``` -Access the application: -- Backend API: http://localhost:8000 -- Frontend: http://localhost:3000 -- API Docs: http://localhost:8000/docs +The backend is published at ; its OpenAPI documentation is at . Either frontend profile publishes the frontend at . -### Option 2: Manual Setup +Compose persists the SQLite data directory in `backup-data` and the backup directory in `backup-storage`. The backend health check requests `/api/health`. -#### Prerequisites +## Manual development -- Python 3.11+ -- Node.js 18+ -- PostgreSQL or MySQL (for database backups) - -#### Backend Setup +### Backend ```bash cd backend python -m venv venv -source venv/bin/activate # On Windows: venv\Scripts\activate +source venv/bin/activate pip install -e ".[dev]" - -# Run the server uvicorn app.main:app --reload --port 8000 ``` -#### Frontend Setup +The backend requires Python 3.11+. Its default `DATABASE_URL` is `sqlite+aiosqlite:///./backup_tool.db`. + +### Frontend ```bash cd frontend @@ -83,139 +55,67 @@ npm install npm run dev ``` -#### Production Build +To build the frontend for the backend to serve: ```bash cd frontend npm run build - -cd ../backend -uvicorn app.main:app --host 0.0.0.0 --port 8000 ``` -## API Documentation - -Once the backend is running, visit: -- Swagger UI: http://localhost:8000/docs -- ReDoc: http://localhost:8000/redoc +When `frontend/dist` exists, the backend mounts its assets and serves the SPA fallback. For a manually built frontend and backend, start the backend as above (or bind explicitly with `uvicorn app.main:app --host 0.0.0.0 --port 8000`). ## Configuration -### Environment Variables +The backend reads these environment variables: -| Variable | Description | Default | -|----------|-------------|---------| -| `DATABASE_URL` | Database connection string | `sqlite+aiosqlite:///./backup_tool.db` | -| `CORS_ORIGINS` | Comma-separated allowed CORS origins | `http://localhost:3000` | -| `SQL_ECHO` | Enable SQL query logging | `false` | -| `BACKUP_STORAGE_PATH` | Path for storing backups | `/app/backups` | +| Variable | Purpose | Default | +| --- | --- | --- | +| `DATABASE_URL` | SQLAlchemy database URL | `sqlite+aiosqlite:///./backup_tool.db` | +| `SQL_ECHO` | Enable SQL query logging when `true` | `false` | +| `CORS_ORIGINS` | Comma-separated allowed origins | `http://localhost:3000` | -### Docker-Specific Configuration +Compose supplies a SQLite URL under `/app/data`, `CORS_ORIGINS=http://localhost:3000`, and mounts persistent data and backup volumes. Configure credentials for backup sources through the application rather than committing them to the repository. -When running with Docker Compose, the following volumes are mounted: -- `backup-data`: Persisted SQLite database at `/app/data` -- `backup-storage`: Backup files at `/app/backups` +## Development and database operations -### Development vs Production - -**Development Mode** (`docker compose --profile dev up -d`): -- Backend hot reload enabled -- Frontend Vite dev server with HMR -- Source code mounted as volumes - -**Production Mode** (`docker compose --profile prod up -d`): -- Optimized frontend build served via nginx -- Backend without reload -- Static assets compiled - -## Troubleshooting - -### Docker Issues - -**Port already in use** -```bash -# Check what's using port 8000 -lsof -i :8000 - -# Or use different ports in docker-compose.yml -``` - -**Container fails to start** -```bash -# Check logs -docker logs backup-tool-backend - -# Rebuild with no cache -docker compose build --no-cache -``` - -**Permission denied on data directory** -```bash -# Fix permissions -docker compose exec backend chown -R backup-tool:backup-tool /app/data -``` - -**Tests fail in Docker** -Tests require development dependencies. Install with: -```bash -docker compose exec backend pip install -e ".[dev]" -``` - -### Manual Setup Issues - -**Python version incompatibility** -Ensure Python 3.11+ is installed: -```bash -python --version -``` - -**Node modules conflicts** -```bash -cd frontend -rm -rf node_modules package-lock.json -npm install -``` - -## Deployment - -### Docker Deployment - -1. Clone the repository -2. Run `docker compose --profile prod up -d` -3. Access at http://localhost:3000 - -### Manual Deployment - -1. Install Python 3.11+ and Node.js 18+ -2. Install backend: `cd backend && pip install -e ".[prod]"` -3. Build frontend: `cd frontend && npm run build` -4. Start backend: `cd backend && uvicorn app.main:app --host 0.0.0.0` - -### Production Considerations - -- Use a reverse proxy (nginx, traefik) for SSL termination -- Set strong credentials for database sources -- Configure backup retention policies -- Monitor disk usage for backup storage -- Use `docker compose -f docker-compose.yml up -d` for production without dev tools - -## Development - -### Running Tests +Run the backend tests: ```bash cd backend pytest ``` -### Database Migrations +The frontend package defines `dev`, `build`, and `preview` scripts; it does not currently define a test script. + +Alembic commands are available from `backend/`: ```bash -cd backend alembic revision --autogenerate -m "Description" alembic upgrade head ``` +## Deployment and operations + +For the provided production frontend container, use: + +```bash +docker compose --profile prod up -d +``` + +This starts the backend and an nginx-served frontend. For manual deployment, build the frontend and run the backend; the backend can serve `frontend/dist` when that directory exists. Choose and protect backup-source credentials, retention policies, and persistent storage for the environment. + +## Repository layout + +```text +. +├── backend/ # FastAPI application, backup engine, Alembic, and tests +│ └── pyproject.toml # Python dependencies and pytest configuration +├── frontend/ # React/Vite frontend +│ └── package.json # Frontend scripts and dependencies +├── docker-compose.yml # Backend and optional frontend profiles +└── docs/ # Project documentation +``` + ## License MIT