docs: refresh README
This commit is contained in:
@@ -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 <http://localhost:8000>; its OpenAPI documentation is at <http://localhost:8000/docs>. Either frontend profile publishes the frontend at <http://localhost:3000>.
|
||||
|
||||
### 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
|
||||
|
||||
Reference in New Issue
Block a user