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

ssh root@your-server-ip

2. Install Docker

# 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

# 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

cd deployment

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env

Configure the following variables:

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

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

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

5. Deploy

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

6. Set Up SSL

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

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

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

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

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

cd /opt/agenda-tasks

# Pull latest code
git pull

# Redeploy
cd deployment/scripts
./deploy.sh

Restart Services

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

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

# 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

# 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

# Check DNS
dig your-domain.com

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

Database Connection Issues

# 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