stones/DEPLOYMENT.md

# Stones Database - Deployment Guide

This guide provides step-by-step instructions for deploying the Stones Database application to a VPS with Nginx and PostgreSQL.

## Prerequisites

- A VPS server with Ubuntu/Debian
- A domain or subdomain (e.g., contacts.boilerhaus.org)
- SSH access to your server
- PostgreSQL database server
- Node.js and npm installed on the server
- Nginx web server
- Let's Encrypt SSL certificates for your domain
- SSH key set up for Gitea access

## Server Setup Checklist

### 1. Update your server
```bash
sudo apt update && sudo apt upgrade -y
```

### 2. Install Node.js using NVM
```bash
# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
source ~/.bashrc

# Install Node.js v18
nvm install 18
nvm use 18
nvm alias default 18
```

### 3. Install and configure PostgreSQL
```bash
sudo apt install postgresql postgresql-contrib -y

# Create a database user and database
sudo -u postgres psql -c "CREATE USER stonesadmin WITH PASSWORD 'your-secure-password';"
sudo -u postgres psql -c "CREATE DATABASE stones;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE stones TO stonesadmin;"
```

### 4. Install Nginx
```bash
sudo apt install nginx -y
```

### 5. Install Let's Encrypt Certbot
```bash
sudo apt install certbot python3-certbot-nginx -y
```

### 6. Generate SSL certificate
```bash
sudo certbot --nginx -d contacts.boilerhaus.org
```

### 7. Set up SSH key for Gitea
If you don't already have an SSH key:
```bash
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
```

Add your public key to your Gitea account at git.boilerhaus.org:
```bash
cat ~/.ssh/id_rsa.pub
```

Copy the output and add it to your Gitea account settings.

## Deployment Process

### 1. Set up your repository on Gitea (git.boilerhaus.org)

Make sure your project is pushed to your Gitea repository at git.boilerhaus.org/boiler/stones. This repository will be used for deployment.

### 2. Clone the repository to your local machine to prepare for deployment
```bash
git clone git@git.boilerhaus.org:boiler/stones.git
cd stones
```

### 3. Prepare the deployment files

Copy the Nginx configuration and deployment script to your repository:

- `contacts-boilerhaus-org.conf`: Nginx configuration for your subdomain
- `deploy.sh`: Deployment script to automate the deployment process

The deployment script is already configured to use your Gitea server:
```
REPO_URL="git@git.boilerhaus.org:boiler/stones.git"
```

### 4. Make the deployment script executable
```bash
chmod +x deploy.sh backup-db.sh
```

### 5. Commit and push these files to your repository
```bash
git add contacts-boilerhaus-org.conf deploy.sh backup-db.sh DEPLOYMENT.md
git commit -m "Add deployment files"
git push origin main
```

### 6. Upload the repository to your server

You can clone the repository directly to your server:

```bash
ssh your-server-user@your-server-ip
git clone git@git.boilerhaus.org:boiler/stones.git
cd stones
```

Make sure your server has the proper SSH key set up to access your Gitea repository.

### 7. Run the deployment script
```bash
./deploy.sh
```

The script will:
- Check if SSH key is set up for git user access
- Clone or update the repository
- Install dependencies
- Build the application
- Create a .env.production file if it doesn't exist
- Set up PM2 for process management
- Configure Nginx

### 8. Update the .env.production file with your actual values
```bash
nano .env.production
```

Make sure to update:
- `DATABASE_URL` with your PostgreSQL credentials
- `AUTH_SECRET` with a strong random string
- Any other configuration variables

### 9. Import your database dump (if you have one)
```bash
psql -U stonesadmin -d stones -f path/to/your/dump.sql
```

## Updating the Application

When you need to update the application, you can either:

1. Run the deployment script again, which will pull the latest changes:
```bash
cd /path/to/repository
./deploy.sh
```

2. Or manually update:
```bash
cd /var/www/stones-database
git pull origin main
npm ci
npm run build
pm2 restart stones-database
```

## Troubleshooting

### Git Access Issues
If you encounter issues with Git access:
```bash
# Test SSH connection to Gitea
ssh -T git@git.boilerhaus.org

# Check if SSH agent is running
eval $(ssh-agent -s)
ssh-add ~/.ssh/id_rsa
```

### Nginx Configuration
If you encounter issues with Nginx:
```bash
sudo nginx -t  # Test Nginx configuration
sudo systemctl reload nginx  # Reload Nginx
sudo systemctl status nginx  # Check Nginx status
```

### PM2 Issues
```bash
pm2 logs stones-database  # View application logs
pm2 list  # Check running processes
pm2 restart stones-database  # Restart the application
```

### Database Connection
If your application can't connect to the database:
1. Check if PostgreSQL is running: `sudo systemctl status postgresql`
2. Verify your `.env.production` file has the correct DATABASE_URL
3. Make sure your PostgreSQL configuration allows connections (check pg_hba.conf)

### SSL Certificate
If you have issues with SSL:
```bash
sudo certbot renew --dry-run  # Test certificate renewal
sudo certbot certificates  # List certificates
```

## Notes

- The application runs on port 3001 locally and is proxied through Nginx
- PM2 is used to keep the application running and restart it if it crashes
- Make sure to back up your database regularly