alex/backup-tool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refresh README

Browse Source
This commit is contained in:
Alex
2026-07-27 15:24:01 +02:00
parent 9f59540686
commit 3965aca42f
1 changed files with 57 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+57 -157
View File
@@ -1,81 +1,53 @@
# Backup Tool # 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) 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.
- **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
## 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.
``` ## Prerequisites
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
```
## 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 ```bash
# Start the backend # Backend only
docker compose up -d docker compose up -d
# Start with frontend (production) # Backend plus the production frontend
docker compose --profile prod up -d 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 docker compose --profile dev up -d
``` ```
Access the application: The backend is published at <http://localhost:8000>; its OpenAPI documentation is at <http://localhost:8000/docs>. Either frontend profile publishes the frontend at <http://localhost:3000>.
- Backend API: http://localhost:8000
- Frontend: http://localhost:3000
- API Docs: http://localhost:8000/docs
### 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+ ### Backend
- Node.js 18+
- PostgreSQL or MySQL (for database backups)
#### Backend Setup
```bash ```bash
cd backend cd backend
python -m venv venv python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate source venv/bin/activate
pip install -e ".[dev]" pip install -e ".[dev]"
# Run the server
uvicorn app.main:app --reload --port 8000 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 ```bash
cd frontend cd frontend
@@ -83,139 +55,67 @@ npm install
npm run dev npm run dev
``` ```
#### Production Build To build the frontend for the backend to serve:
```bash ```bash
cd frontend cd frontend
npm run build npm run build
cd ../backend
uvicorn app.main:app --host 0.0.0.0 --port 8000
``` ```
## API Documentation 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`).
Once the backend is running, visit:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
## Configuration ## Configuration
### Environment Variables The backend reads these environment variables:
| Variable | Description | Default | | Variable | Purpose | Default |
|----------|-------------|---------| | --- | --- | --- |
| `DATABASE_URL` | Database connection string | `sqlite+aiosqlite:///./backup_tool.db` | | `DATABASE_URL` | SQLAlchemy database URL | `sqlite+aiosqlite:///./backup_tool.db` |
| `CORS_ORIGINS` | Comma-separated allowed CORS origins | `http://localhost:3000` | | `SQL_ECHO` | Enable SQL query logging when `true` | `false` |
| `SQL_ECHO` | Enable SQL query logging | `false` | | `CORS_ORIGINS` | Comma-separated allowed origins | `http://localhost:3000` |
| `BACKUP_STORAGE_PATH` | Path for storing backups | `/app/backups` |
### 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: ## Development and database operations
- `backup-data`: Persisted SQLite database at `/app/data`
- `backup-storage`: Backup files at `/app/backups`
### Development vs Production Run the backend tests:
**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
```bash ```bash
cd backend cd backend
pytest 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 ```bash
cd backend
alembic revision --autogenerate -m "Description" alembic revision --autogenerate -m "Description"
alembic upgrade head 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 ## License
MIT MIT