backup-tool/README.md

# Backup Tool

A modern backup management application with a FastAPI backend and React frontend.

## Features

- **Source Type**: Local filesystem
- **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

```
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/    # Local source adapter
│   │   ├── 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

### Option 1: Docker (Recommended)

The easiest way to run the backup tool is using Docker Compose:

```bash
# Start the backend
docker compose up -d

# Start with frontend (production)
docker compose --profile prod up -d

# Start with frontend (development with hot reload)
docker compose --profile dev up -d
```

Access the application:

- Backend API: <http://localhost:8000>
- Frontend: <http://localhost:3000>
- API Docs: <http://localhost:8000/docs>

### Option 2: Manual Setup

#### Prerequisites

- Python 3.11+
- Node.js 18+
- PostgreSQL or MySQL (for database backups)

#### Backend Setup

```bash
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

# Run the server
uvicorn app.main:app --reload --port 8000
```

#### Frontend Setup

```bash
cd frontend
npm install
npm run dev
```

#### Production Build

```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>

## Configuration

### 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` |

### Docker-Specific Configuration

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 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

```bash
cd backend
pytest
```

### Database Migrations

```bash
cd backend
alembic revision --autogenerate -m "Description"
alembic upgrade head
```

## License

MIT