LafaekStreet Backend - Deployment Guide

How to deploy and update the FastAPI backend on AWS Lightsail from your Mac.

---

Scripts Overview

Script	Purpose	Run From
new_deploy_server.sh	First-time full deployment	Your Mac
new_update_server.sh	Update existing server	Your Mac

Both scripts are located in: lafaekstreet_backend/

---

Architecture

Your Mac                          AWS Lightsail (Ubuntu 22.04)
────────                          ─────────────────────────────
new_deploy_server.sh  ──SSH/SCP──>  Nginx (port 80/443)
new_update_server.sh                   │
                                  Gunicorn + Uvicorn (port 8000)
                                       │
                                  FastAPI Application
                                       │
                          ┌────────┬───┴───┬──────────┬────────┐
                          v        v       v          v        v
                       Aiven    Aiven    AWS S3    Bedrock   Hedera
                       Postgres  Valkey  (images)   (AI)   (blockchain)

---

Prerequisites

Before running any script, make sure you have:

1. AWS CLI configured (aws configure)
2. .env file in the lafaekstreet_backend/ directory
3. Run scripts from the lafaekstreet_backend/ directory

cd /path/to/LafaekStreet/lafaekstreet_backend

---

First-Time Deployment

Run the deploy script

cd lafaekstreet_backend
./new_deploy_server.sh

What it does (step by step)

Step	Action	Details
1	SSH Key Setup	Creates ~/.ssh/lafaekstreet-key.pem if not exists
2	Lightsail Instance	Creates lafaekstreet-api instance (or uses existing)
3	Network	Configures firewall: ports 22, 80, 443, 8000
4	Wait for SSH	Waits until instance is accessible
5	Package Code	Creates tar.gz excluding .git, venv, pycache, etc.
6	Upload	Uploads code to instance via SCP
7	System Deps	Installs Python, Nginx, Certbot, Fail2Ban, etc.
8	App Setup	Creates venv, installs pip dependencies, log/backup dirs
9	Systemd Service	Gunicorn + Uvicorn workers, auto-restart, logging
10	Nginx	Reverse proxy, rate limiting, security headers, upload timeouts
11	Fail2Ban	SSH + Nginx brute-force protection
12	Log Rotation	14-day retention, daily rotation
13	Start Services	Starts app and verifies it's running
14	SSL Certificate	Certbot with Let's Encrypt (requires DNS configured)

Configuration (edit in script if needed)

INSTANCE_NAME="lafaekstreet-api"
BUNDLE_ID="micro_3_0"           # 1 GB RAM, 2 vCPUs, 40 GB SSD
AVAILABILITY_ZONE="us-east-1a"
REGION="us-east-1"
DOMAIN="api.lafaekstreet.com"
KEY_NAME="lafaekstreet-key"

After deployment

Instance Name: lafaekstreet-api
SSH Key:       ~/.ssh/lafaekstreet-key.pem
App Directory: /home/ubuntu/lafaekstreet
Logs:          /var/log/lafaekstreet/
Backups:       /home/ubuntu/backups/

---

Updating the Server

Run the update script

cd lafaekstreet_backend
./new_update_server.sh

Update Options

You'll be prompted to choose:

Option 1: Environment Variables Only

Updates .env file on the server and restarts the service.

• Backs up existing .env on server (timestamped)
• Uploads your local .env
• Sets file permissions to 600
• Restarts service
• Verifies service is running

Use when: You changed API keys, database URLs, or config values.

Option 2: Full Application Update

Updates code + .env + dependencies with safety checks.

• Creates backup on server (tar.gz)
• Uploads all code from your Mac
• Installs/updates pip dependencies
• Tests application import (from app.main import app)
• Restarts service
• Health check (3 retries on /health)
• Auto-rollback if anything fails
• Reloads Nginx
• Cleans old backups (keeps last 5)

Use when: You changed code AND environment variables.

Option 3: Code Only

Same as Option 2 but preserves the existing .env on the server.

• Saves .env before extracting new code
• Restores .env after extraction
• All the same safety checks as Option 2

Use when: You only changed code, not environment variables.

Safety Features

Feature	Description
Auto Backup	Backs up current code before every update
Import Test	Validates from app.main import app before restart
Health Check	Hits /health endpoint with 3 retries
Auto Rollback	Restores backup if import, restart, or health check fails
Backup Cleanup	Keeps only the last 5 backups

---

Useful Commands

From your Mac

# SSH to server
ssh -i ~/.ssh/lafaekstreet-key.pem ubuntu@<INSTANCE_IP>

# Check service status
ssh -i ~/.ssh/lafaekstreet-key.pem ubuntu@<INSTANCE_IP> 'sudo systemctl status lafaekstreet'

# View live logs
ssh -i ~/.ssh/lafaekstreet-key.pem ubuntu@<INSTANCE_IP> 'sudo journalctl -u lafaekstreet -f'

# Restart service
ssh -i ~/.ssh/lafaekstreet-key.pem ubuntu@<INSTANCE_IP> 'sudo systemctl restart lafaekstreet'

On the server (after SSH)

# Service management
sudo systemctl start lafaekstreet
sudo systemctl stop lafaekstreet
sudo systemctl restart lafaekstreet
sudo systemctl status lafaekstreet

# Logs
sudo journalctl -u lafaekstreet -f              # Live app logs
sudo tail -f /var/log/lafaekstreet/error.log     # Error log
sudo tail -f /var/log/nginx/lafaekstreet_access.log  # Nginx access

# Health check
curl http://localhost:8000/health

# System resources
free -h && df -h

---

Troubleshooting

Service won't start

# Check logs
sudo journalctl -u lafaekstreet -n 50

# Test import manually
cd ~/lafaekstreet && source venv/bin/activate
python -c "from app.main import app"

# Check .env exists
ls -la ~/lafaekstreet/.env

502 Bad Gateway

# App not running
sudo systemctl start lafaekstreet

# Check port
sudo ss -tlnp | grep 8000

Health check fails after update

The script auto-rolls back. Check what changed:

# View recent logs
sudo journalctl -u lafaekstreet -n 30

# Manual rollback (if needed)
ls ~/backups/  # find latest backup
sudo tar -xzf ~/backups/backup_YYYYMMDD_HHMMSS.tar.gz -C ~/lafaekstreet
sudo systemctl restart lafaekstreet

SSL issues

# Re-run certbot
sudo certbot --nginx -d api.lafaekstreet.com

# Check cert expiry
sudo certbot certificates

# Test auto-renewal
sudo certbot renew --dry-run

---

Server Configuration Files

File	Location on Server	Purpose
Systemd service	/etc/systemd/system/lafaekstreet.service	Process management
Nginx config	/etc/nginx/sites-available/lafaekstreet	Reverse proxy
Environment	~/lafaekstreet/.env	App configuration
Log rotation	/etc/logrotate.d/lafaekstreet	Log cleanup
Fail2Ban	/etc/fail2ban/jail.local	Brute-force protection
App logs	/var/log/lafaekstreet/	Application logs
Nginx logs	/var/log/nginx/lafaekstreet_*.log	Web server logs
Backups	~/backups/	Pre-update backups