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

sudo apt update && sudo apt upgrade -y

2. Install Node.js using NVM

# 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

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

sudo apt install nginx -y

5. Install Let's Encrypt Certbot

sudo apt install certbot python3-certbot-nginx -y

6. Generate SSL certificate

sudo certbot --nginx -d contacts.boilerhaus.org

7. Set up SSH key for Gitea

If you don't already have an SSH key:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Add your public key to your Gitea account at git.boilerhaus.org:

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

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

chmod +x deploy.sh backup-db.sh

5. Commit and push these files to your repository

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:

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

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

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)

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:

cd /path/to/repository
./deploy.sh

2. Or manually update:

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:

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

sudo nginx -t  # Test Nginx configuration
sudo systemctl reload nginx  # Reload Nginx
sudo systemctl status nginx  # Check Nginx status

PM2 Issues

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:

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