AgendaTasks/deployment/README.md

# Agenda Tasks - Server Deployment Guide

This guide explains how to deploy the Agenda Tasks backend to a Linode server.

## Server Requirements

**Recommended: Linode 2GB ($12/month)**
- 1 CPU core
- 2 GB RAM
- 50 GB SSD storage
- Ubuntu 22.04 LTS

This configuration is sufficient for a small to medium user base.

## Prerequisites

1. A Linode server with Ubuntu 22.04 LTS
2. A domain name pointing to your server's IP address
3. SSH access to the server

## Quick Start

### 1. Connect to Your Server

```bash
ssh root@your-server-ip
```

### 2. Install Docker

```bash
# Update system
apt update && apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Install Docker Compose
apt install docker-compose-plugin -y

# Start Docker
systemctl enable docker
systemctl start docker
```

### 3. Clone the Repository

```bash
# Create app directory
mkdir -p /opt/agenda-tasks
cd /opt/agenda-tasks

# Clone repository (or copy files)
git clone https://your-repo-url.git .
```

### 4. Configure Environment

```bash
cd deployment

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env
```

Configure the following variables:

```bash
# Database Configuration
DB_USER=agenda
DB_PASSWORD=<generate-a-secure-password>
DB_NAME=agenda_tasks

# Application Configuration
SECRET_KEY=<generate-a-32-character-secret>
DEBUG=false

# Domain Configuration
DOMAIN=your-domain.com
EMAIL=admin@your-domain.com
```

**Generate Secure Values:**

```bash
# Generate DB_PASSWORD (32 characters)
openssl rand -base64 32

# Generate SECRET_KEY (32 characters)
openssl rand -hex 32
```

### 5. Deploy

```bash
cd /opt/agenda-tasks/deployment/scripts
./deploy.sh
```

### 6. Set Up SSL

After DNS propagation (may take up to 48 hours):

```bash
./setup-ssl.sh
```

## Directory Structure

```
deployment/
├── docker/
│   ├── Dockerfile.backend    # Backend container
│   └── docker-compose.yml    # Service orchestration
├── nginx/
│   ├── nginx.conf           # Main nginx config
│   └── conf.d/
│       └── default.conf     # Server block config
├── scripts/
│   ├── deploy.sh            # Deployment script
│   ├── backup-db.sh         # Database backup
│   └── setup-ssl.sh         # SSL certificate setup
├── backups/                 # Database backups (created automatically)
├── .env.example             # Environment template
└── README.md               # This file
```

## Services

| Service | Port | Description |
|---------|------|-------------|
| PostgreSQL | 5432 (internal) | Database |
| Backend | 8000 (internal) | FastAPI application |
| Nginx | 80, 443 | Reverse proxy with SSL |
| Certbot | - | SSL certificate management |

## API Endpoints

After deployment, your API will be available at:

```
https://your-domain.com/
```

### Authentication Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /auth/register | Register new user |
| POST | /auth/login | Login and get tokens |
| POST | /auth/refresh | Refresh access token |
| GET | /auth/me | Get current user info |

### Task Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /tasks?date=YYYY-MM-DD | Get tasks for date |
| POST | /tasks | Create new task |
| GET | /tasks/{id} | Get task by ID |
| PUT | /tasks/{id} | Update task |
| DELETE | /tasks/{id} | Delete task |
| PATCH | /tasks/{id}/toggle | Toggle task status |
| POST | /tasks/{id}/reschedule | Reschedule task |

### API Documentation

Interactive API documentation is available at:
- Swagger UI: `https://your-domain.com/docs`
- ReDoc: `https://your-domain.com/redoc`

## Maintenance

### View Logs

```bash
cd /opt/agenda-tasks/deployment/docker

# All services
docker compose logs -f

# Specific service
docker compose logs -f backend
docker compose logs -f nginx
docker compose logs -f db
```

### Database Backup

```bash
cd /opt/agenda-tasks/deployment/scripts
./backup-db.sh
```

Backups are stored in `/opt/agenda-tasks/deployment/backups/` and automatically cleaned up after 7 days.

### Restore Database

```bash
cd /opt/agenda-tasks/deployment/docker

# Stop backend
docker compose stop backend

# Restore from backup
gunzip < ../backups/agenda_tasks_YYYYMMDD_HHMMSS.sql.gz | \
  docker compose exec -T db psql -U agenda agenda_tasks

# Start backend
docker compose start backend
```

### Update Application

```bash
cd /opt/agenda-tasks

# Pull latest code
git pull

# Redeploy
cd deployment/scripts
./deploy.sh
```

### Restart Services

```bash
cd /opt/agenda-tasks/deployment/docker

# Restart all
docker compose restart

# Restart specific service
docker compose restart backend
```

## Security Checklist

- [ ] Strong database password (32+ characters)
- [ ] Strong secret key (32+ characters)
- [ ] SSL certificate installed
- [ ] Firewall configured (ports 80, 443 only)
- [ ] Regular backups enabled
- [ ] DEBUG=false in production

### Configure Firewall

```bash
# Allow SSH
ufw allow ssh

# Allow HTTP/HTTPS
ufw allow 80/tcp
ufw allow 443/tcp

# Enable firewall
ufw enable
```

## Flutter App Configuration

When building the Flutter app for production, specify the API URL:

```bash
# Android APK
flutter build apk --dart-define=API_URL=https://your-domain.com

# iOS
flutter build ios --dart-define=API_URL=https://your-domain.com
```

## Troubleshooting

### Backend Not Starting

```bash
# Check logs
docker compose logs backend

# Common issues:
# - Database connection failed: Check DB_PASSWORD
# - Import errors: Rebuild with --no-cache
docker compose build --no-cache backend
```

### SSL Certificate Failed

```bash
# Check DNS
dig your-domain.com

# DNS should point to your server IP
# Wait for propagation if recently changed
```

### Database Connection Issues

```bash
# Check database is running
docker compose ps db

# Check database logs
docker compose logs db

# Test connection
docker compose exec db psql -U agenda -d agenda_tasks -c "SELECT 1"
```

## Support

For issues or questions:
1. Check the logs first
2. Review this documentation
3. Contact the development team