Sword Backend Local Deployment Guide with HTTPS¶

This guide explains how to deploy the Sword Backend application with HTTPS on a Linux server without requiring a domain name, using self-signed certificates.

Prerequisites¶

A Linux server (Ubuntu/Debian recommended)
Root or sudo access to the server

Deployment Steps¶

1. Clone the Repository¶

First, clone the repository to your local machine or directly to the server.

git clone <repository-url> sword-backend
cd sword-backend

2. Update Database Password¶

Edit the scripts/shell/master_deploy_local.sh script and update the database password:

# Open the file
nano scripts/shell/master_deploy_local.sh

# Update this line
DB_PASSWORD="your_secure_password"  # Change this to a secure password

3. Make the Scripts Executable¶

chmod +x scripts/shell/master_deploy_local.sh scripts/shell/deploy_https_local.sh scripts/shell/setup_database.sh scripts/shell/run_migrations.sh

4. Run the Master Deployment Script¶

sudo ./scripts/shell/master_deploy_local.sh

The script will: - Set up a PostgreSQL database - Install all necessary dependencies - Set up a Python virtual environment - Generate self-signed SSL certificates - Configure Nginx as a reverse proxy with HTTPS - Set up your application as a systemd service - Start all services - Run database migrations

5. Verify the Deployment¶

After the script completes, verify that your application is running:

# Check the status of the application service
sudo systemctl status sword-backend

# Check Nginx status
sudo systemctl status nginx

# Test the API (replace SERVER_IP with your actual server IP)
curl -k https://SERVER_IP/docs

Environment Variables¶

The deployment script will create a .env file with default values. You may want to update some of these values after deployment:

# Edit the .env file
nano /home/projects/sword-backend/.env

Make sure it contains all necessary environment variables:

DATABASE_URL=postgresql://sword_user:your_secure_password@localhost:5432/sword_db
SECRET_KEY=your-secret-key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
MAIL_USERNAME=your-email@example.com
MAIL_PASSWORD=your-password
MAIL_FROM=your-email@example.com
MAIL_PORT=587
MAIL_SERVER=smtp.gmail.com

Accessing the Application¶

You can access your application using the server's IP address:

https://SERVER_IP

Since you're using a self-signed certificate, your browser will show a security warning. You'll need to add a security exception to proceed.

Troubleshooting¶

Check Logs¶

If you encounter issues, check the logs:

# Application logs
sudo journalctl -u sword-backend

# Nginx logs
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/access.log

SSL Certificate Issues¶

If you have issues with the self-signed certificate:

# Regenerate the certificate
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout /home/projects/sword-backend/ssl/nginx-selfsigned.key \
    -out /home/projects/sword-backend/ssl/nginx-selfsigned.crt \
    -subj "/C=US/ST=State/L=City/O=Organization/CN=SERVER_IP"

# Restart Nginx
sudo systemctl restart nginx

Firewall Configuration¶

Make sure your firewall allows HTTP (80) and HTTPS (443) traffic:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Maintenance¶

Updating the Application¶

To update the application:

Pull the latest changes from the repository
Copy the updated files to the deployment directory
Restart the service

cd /path/to/local/repository
git pull
rsync -av --exclude 'venv' --exclude '__pycache__' --exclude '.git' ./ /home/projects/sword-backend/
sudo systemctl restart sword-backend

Database Backups¶

It's recommended to set up regular database backups:

# Example PostgreSQL backup command
pg_dump -U postgres sword_db > /path/to/backup/sword_db_$(date +%Y%m%d).sql

SSL Certificate Renewal¶

Self-signed certificates expire after the period specified during creation (365 days by default). To renew:

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout /home/projects/sword-backend/ssl/nginx-selfsigned.key \
    -out /home/projects/sword-backend/ssl/nginx-selfsigned.crt \
    -subj "/C=US/ST=State/L=City/O=Organization/CN=SERVER_IP"

sudo systemctl restart nginx