# Teren App - Ubuntu 24.04 VPS Deployment Guide

This guide covers the complete setup of the Teren App on Ubuntu 24.04 using Docker, including SSL, WireGuard VPN, and automated deployments.

## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Initial VPS Setup](#initial-vps-setup)
3. [Docker Installation](#docker-installation)
4. [WireGuard VPN Setup](#wireguard-vpn-setup) ⚠️ **SETUP FIRST - APP IS VPN-ONLY**
5. [Application Setup](#application-setup)
6. [SSL Certificate Setup](#ssl-certificate-setup)
7. [Portainer Setup](#portainer-setup)
8. [Automated Deployment Setup](#automated-deployment-setup)
9. [Monitoring & Maintenance](#monitoring--maintenance)
10. [Troubleshooting](#troubleshooting)

---

## Prerequisites

- Ubuntu 24.04 VPS with root access
- Domain name pointed to your VPS IP (optional - can use IP only)
- Self-hosted Gitea server
- At least 2GB RAM (4GB recommended)
- 20GB+ storage

**IMPORTANT:** This application is configured to be accessible ONLY through WireGuard VPN. The app will NOT be publicly accessible.

---

## Initial VPS Setup

### 1. Update System

```bash
sudo apt update && sudo apt upgrade -y
```

### 2. Create Deploy User

```bash
# Create user
sudo adduser deployer
sudo usermod -aG sudo deployer

# Switch to deploy user
su - deployer
```

### 3. Configure Firewall

```bash
# Install UFW
sudo apt install ufw -y

# Allow SSH, HTTP, HTTPS, and WireGuard
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 51820/udp  # WireGuard

# Enable firewall
sudo ufw enable
sudo ufw status
```

### 4. Install Essential Tools

```bash
sudo apt install -y \
    git \
    curl \
    wget \
    unzip \
    vim \
    htop \
    software-properties-common
```

---

## Docker Installation

### 1. Install Docker

```bash
# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

### 2. Configure Docker

```bash
# Add user to docker group
sudo usermod -aG docker $USER

# Enable Docker service
sudo systemctl enable docker
sudo systemctl start docker

# Verify installation
docker --version
docker compose version

# Log out and back in for group changes to take effect
exit
su - deployer
```

---WireGuard VPN Setup

⚠️ **CRITICAL: Setup WireGuard FIRST before the application!** The app is configured to be VPN-only and will not be publicly accessible.

### 1. Enable Kernel Modules

```bash
# Load WireGuard kernel module
sudo apt install -y wireguard-tools
sudo modprobe wireguard

# Make it persistent
echo "wireguard" | sudo tee -a /etc/modules
```

### 2. Configure Environment

```bash
cd /var/www/Teren-app

# Edit .env file
vim .env
```

Set these WireGuard variables:
- `WG_SERVERURL`: Your VPS public IP or domain (e.g., `vpn.example.com` or `192.168.1.100`)
- `WG_UI_PASSWORD`: Strong password for WireGuard dashboard

### 3. Start WireGuard Container

```bash
# Start only WireGuard first
docker compose up -d wireguard

# Wait for it to initialize
sleep 10

# Check status
docker compose logs wireguard
```

### 4. Access WireGuard Dashboard

The WireGuard Web UI is temporarily accessible publicly for initial setup:

**URL:** `http://YOUR_VPS_IP:51821`

Login with the password you set in `WG_UI_PASSWORD`.

### 5. Create Your First Client

1. In the WireGuard dashboard, click **"New Client"**
2. Give it a name (e.g., "MyLaptop")
3. Click the QR code or download the config file
4. Install WireGuard on your device:
   - **Windows:** https://www.wireguard.com/install/
   - **macOS:** App Store
   - **Linux:** `sudo apt install wireguard`
   - **iOS/Android:** App Store / Play Store

5. ImpoStart Application Containers

**Note:** Make sure you're connected to the WireGuard VPN before proceeding.

```bash
# Start all application containers
docker compose up -d postgres redis app nginx certbot

# Verify containers are running
docker compose ps

# Test application (from your VPN-connected machine)
curl http://10.13.13.1
# Or in browser: http://10.13.13.1

You should get responses from the VPN gateway.

### 7. Secure WireGuard Dashboard (After Setup)

After creating your initial clients, secure the WireGuard UI by editing `docker-compose.yaml`:
**Note:** SSL certificates are optional since the app is VPN-only. You can use self-signed certificates or skip SSL entirely for internal VPN access. However, if you want proper SSL:

### Option 1: Self-Signed Certificates (Recommended for VPN-only)

```bash
# Generate self-signed certificate
sudo mkdir -p docker/nginx/ssl
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout docker/nginx/ssl/selfsigned.key \
    -out docker/nginx/ssl/selfsigned.crt \
    -subj "/C=SI/ST=Slovenia/L=Ljubljana/O=TerenApp/CN=10.13.13.1"

# Update nginx config to use self-signed cert
vim docker/nginx/conf.d/app.conf
```

Update SSL paths:
```nginx
ssl_certificate /etc/nginx/ssl/selfsigned.crt;
ssl_certificate_key /etc/nginx/ssl/selfsigned.key;
```

```bash
# Restart nginx
docker compose restart nginx

# Test (ignore certificate warning)
curl -k https://10.13.13.1
```

### Option 2: Let's Encrypt (If using domain name)

Only if you have a domain pointing to your VPS and want valid SSL:

```bash
# Temporarily allow port 80 publicly
sudo ufw allow 80/tcp

# Request certificate
docker compose run --rm certbot certonly \
    --standalone \
    --preferred-challenges http \
    --email your-email@example.com \
    --agree-tos \
    --no-eff-email \
    -d your-domain.com

# Block port 80 again
sudo ufw delete allow 80/tcp

# Update nginx config with Let's Encrypt paths
# Restart nginx
docker compose restart nginx
```

### Option 3: No SSL (HTTP Only)

For internal VPN-only access, you can skip SSL entirely:

```bash
# Edit nginx config to remove HTTPS server block
vim docker/nginx/conf.d/app.conf

# Keep only the HTTP (port 80) server block
# Restart nginx
docker compose restart nginx

# Access via: http://10.13.13.1

```bash
# Create project directory
sudo mkdir -p /var/www
sudo chown -R $USER:$USER /var/www
cd /var/www

# Clone from your Gitea server
git clone git@your-gitea-server.com:username/Teren-app.git
cd Teren-app
```

### 2. Setup Environment

```bash
# Copy example files
cp .env.production.example .env
cp docker-compose.yaml.example docker-compose.yaml

# Edit .env file with your actual values
vim .env
```

**Important:** Update these values in `.env`:
- `APP_KEY` - Generate with `php artisan key:generate` (run after first container start)
- `APP_URL` - Your domain
- `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD` - Strong database credentials
- `PGADMIN_EMAIL`, `PGADMIN_PASSWORD` - pgAdmin credentials

### 3. Update Docker Compose

Edit `docker-compose.yaml` and update:
- Replace `example.com` with your domain in nginx volume mounts
- Update environment variables as needed

### 4. Create Required Directories

```bash
# Create docker directories
mkdir -p docker/nginx/conf.d
mkdir -p docker/nginx/ssl
mkdir -p docker/certbot/conf
mkdir -p docker/certbot/www
mkdir -p docker/postgres/init
mkdir -p docker/supervisor/conf.d
mkdir -p docker/php

# Set permissions
sudo chown -R $USER:$USER docker/
```

### 5. Update Nginx Configuration

Edit `docker/nginx/conf.d/app.conf` and replace `example.com` with your actual domain.

### 6. Initial SSL Certificate (HTTP-only first)

Before getting SSL certificates, modify nginx config temporarily:

```bash
# Comment out SSL sections in docker/nginx/conf.d/app.conf
# Keep only the HTTP (port 80) server block

# Start containers
docker compose up -d postgres redis app nginx

# Verify nginx is running
docker compose ps
curl http://your-domain.com  # Should get some response
```

---

## SSL Certificate Setup

### 1. Obtain Initial Certificate

```bash
# Request certificate for your domain
docker compose run --rm certbot certonly \
    --webroot \
    --webroot-path=/var/www/certbot \
    --email your-email@example.com \
    --agree-tos \
    --no-eff-email \
    -d your-domain.com \
    -d www.your-domain.com
```

### 2. Enable HTTPS in Nginx

```bash
# Uncomment SSL sections in docker/nginx/conf.d/app.conf
vimPortainer Setup

Portainer provides a web UI for managing Docker containers, images, networks, and volumes.

### 1. Access Portainer

**Prerequisites:** Must be connected to WireGuard VPN

**URL:** `http://10.13.13.1:9000` or `https://10.13.13.1:9443`

### 2. Initial Setup

On first access:

1. Create admin account:
   - Username: `admin`
   - Password: (set a strong password)

2. Select **"Docker"** environment

3. Click **"Connect"**

### 3. Portainer Features

- **Containers:** Start, stop, restart, view logs
- **Images:** Pull, build, remove images
- **Networks:** Manage Docker networks
- **Volumes:** View and manage volumes
- **Stacks:** Deploy docker-compose stacks
- **Events:** Real-time Docker events

### 4. Useful Portainer Operations

**View Container Logs:**
1. Go to Containers
2. Click on container name
3. Click "Logs"
4. Select "Auto-refresh"

**Execute Commands:**
1. Go to Containers
2. Click on container
3. Click "Console"
4. Select "/bin/sh" or "/bin/bash"

**Update Container:**
1. Go to Containers
2. Click container name
3. Click "Recreate"
4. Enable "Pull latest image"

### 5. Security Notes

- Portainer is only accessible via VPN (bound to 10.13.13.1)
- Always use strong passwords
- Enable 2FA if deploying Portainer Business Edition
- Regularly backup Portainer data volume
  - "127.0.0.1:5432:5432"

# To:
ports:
  - "10.13.13.1:5432:5432"  # WireGuard VPN subnet
```

Then restart:
```bash
docker compose down
docker compose up -d
```

### 5. Connect Client

Install WireGuard on your local machine:
- **Linux:** `sudo apt install wireguard`
- **macOS:** Download from App Store
- **Windows:** Download from wireguard.com

Import the client config and connect.

### 6. Access Services via VPN

Once connected to VPN:
- pgAdmin: `http://10.13.13.1:5050`
- PostgreSQL: `10.13.13.1:5432`

---

## Automated Deployment Setup

### Method 1: Gitea Webhooks (Recommended)

#### 1. Setup Webhook Listener on VPS

```bash
# Create webhook handler script
sudo vim /usr/local/bin/webhook-handler.sh
```

Add:
```bash
#!/bin/bash
# Simple webhook handler

PORT=9000
SECRET="your-webhook-secret"

while true; do
    echo "Listening for webhooks on port $PORT..."
    echo -e "HTTP/1.1 200 OK\n\n" | nc -l -p $PORT -q 1 > /tmp/webhook.log
    
    # Verify secret (basic)
    if grep -q "$SECRET" /tmp/webhook.log; then
        echo "Valid webhook received, deploying..."
        cd /var/www/Teren-app && ./deploy.sh >> /var/log/deploy.log 2>&1
    fi
done
```

```bash
# Make executable
sudo chmod +x /usr/local/bin/webhook-handler.sh

# Create systemd service
sudo vim /etc/systemd/system/webhook-handler.service
```

Add:
```ini
[Unit]
Description=Gitea Webhook Handler
After=network.target

[Service]
Type=simple
User=deployer
ExecStart=/usr/local/bin/webhook-handler.sh
Restart=always

[Install]
WantedBy=multi-user.target
```

```bash
# Enable and start
sudo systemctl enable webhook-handler
sudo systemctl start webhook-handler

# Allow webhook port in firewall
sudo ufw allow 9000/tcp
```

#### 2. Configure Gitea Webhook

In your Gitea repository:
1. Go to Settings → Webhooks
2. Add webhook:
   - Payload URL: `http://your-vps-ip:9000`
   - Secret: `your-webhook-secret`
   - Trigger: Push events on `main` branch
3. Test webhook

### Method 2: Gitea Actions (Recommended for CI/CD)

#### 1. Enable Gitea Actions

On your Gitea server, edit `app.ini`:
```ini
[actions]
ENABLED = true
```

#### 2. Setup Actions Runner on VPS

```bash
# Download runner
cd ~
wget https://gitea.com/gitea/act_runner/releases/latest/download/act_runner-linux-amd64
chmod +x act_runner-linux-amd64
sudo mv act_runner-linux-amd64 /usr/local/bin/act-runner

# Register runner
act-runner register --instance https://your-gitea.com --token YOUR_RUNNER_TOKEN

# Generate config
act-runner generate-config > runner-config.yaml

# Create systemd service
sudo vim /etc/systemd/system/act-runner.service
```

Add:
```ini
[Unit]
Description=Gitea Actions Runner
After=network.target

[Service]
Type=simple
User=deployer
WorkingDirectory=/home/deployer
ExecStart=/usr/local/bin/act-runner daemon --config /home/deployer/runner-config.yaml
Restart=always

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable act-runner
sudo systemctl start act-runner
```

#### 3. Create Workflow File

In your repository, create `.gitea/workflows/deploy.yaml`:

```yaml
name: Deploy to Production

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy via SSH
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.VPS_HOST }}
          username: deployer
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/Teren-app
            ./deploy.sh
```

Add secrets in Gitea: Settings → Secrets → Actions
- `VPS_HOST`: Your VPS IP/domain
- `SSH_PRIVATE_KEY`: SSH key for deployer user

### 3. Make Deploy Script Executable

```bash
cd /var/www/Teren-app
chmod +x deploy.sh

# Edit script to match your setup
vim deploy.sh
```

### 4. Test Deployment

```bash
# Manual test
./deploy.sh

# Or trigger via git push
git commit --allow-empty -m "Test deployment"
git push origin main
```

---

## Application Initialization

### 1. Start All Containers

```bash
cd /var/www/Teren-app
docker compose up -d
```

### 2. Generate Application Key

```bash
docker compose exec app php artisan key:generate
```

### 3. Run Migrations

```bash
docker compose exec app php artisan migrate --force
```

### 4. Seed Database (if needed)

```bash
docker compose exec app php artisan db:seed --force
```

### 5. Cache Configuration

```bash
docker compose exec app php artisan config:cache
docker compose exec app php artisan route:cache
docker compose exec app php artisan view:cache
```

### 6. Set Permissions

```bash
docker compose exec app chown -R www:www /var/www/storage
docker compose exec app chown -R www:www /var/www/bootstrap/cache
```

### 7. Verify Installation

```bash
# Check containers
docker compose ps

# Check logs
docker compose logs -f app

# Test application
curl https://your-domain.com
```

---

## Monitoring & Maintenance

### Container Management

```bash
# View all containers
docker compose ps

# View logs
docker compose logs -f app        # Laravel app
docker compose logs -f nginx      # Nginx
docker compose logs -f postgres   # Database

# Restart containers
docker compose restart app
docker compose restart nginx

# Stop all
docker compose down

# Start all
docker compose up -d
```

### Queue Workers

```bash
# Check queue worker status
docker compose exec app supervisorctl status

# Restart qServices via VPN

**All services are only accessible when connected to WireGuard VPN:**

| Service | URL | Purpose |
|---------|-----|---------|
| Laravel App | `http://10.13.13.1` | Main application |
| pgAdmin | `http://10.13.13.1:5050` | PostgreSQL UI |
| Portainer | `http://10.13.13.1:9000` | Docker management |
| WireGuard UI | `http://10.13.13.1:51821` | VPN management |
| PostgreSQL | `10.13.13.1:5432` | Direct DB connection |
| Redis | `10.13.13.1:6379` | Direct Redis connection |

**pgAdmin Setup:**
1. Connect to VPN
2. Open: `http://10.13.13.1:5050`
3. Login with `PGADMIN_EMAIL` and `PGADMIN_PASSWORD`
4. Add server:
   - Host: `postgres` (or `10.13.13.1` if connecting externally)nt

```bash
# Connect to PostgreSQL
docker compose exec postgres psql -U teren_user -d teren_app

# Backup database
docker compose exec postgres pg_dump -U teren_user teren_app > backup-$(date +%Y%m%d).sql

# Restore database
docker compose exec -T postgres psql -U teren_user teren_app < backup-20260113.sql
```

### Access pgAdmin

Via WireGuard VPN:
1. Connect to VPN
2. Open browser: `http://10.13.13.1:5050`
3. Login with `PGADMIN_EMAIL` and `PGADMIN_PASSWORD`
4. Add server:
   - Host: `postgres`
   - Port: `5432`
   - Database: Your `DB_DATABASE`
   - Username: Your `DB_USERNAME`
   - Password: Your `DB_PASSWORD`

### Log Rotation

```bash
# Install logrotate
sudo apt install logrotate -y

# Create config
sudo vim /etc/logrotate.d/teren-app
```

Add:
```
/var/www/Teren-app/storage/logs/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 deployer deployer
    sharedscripts
}
```

### Automated Backups

Create backup script:
```bash
sudo vim /usr/local/bin/backup-teren.sh
```

Add:
```bash
#!/bin/bash
BACKUP_DIR="/backups/teren-app"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Backup database
docker compose -f /var/www/Teren-app/docker-compose.yaml exec -T postgres \
    pg_dump -U teren_user teren_app | gzip > $BACKUP_DIR/db-$DATE.sql.gz

# Backup uploads
tar -czf $BACKUP_DIR/storage-$DATE.tar.gz -C /var/www/Teren-app storage/app/public

# Keep only last 7 days
find $BACKUP_DIR -type f -mtime +7 -delete

echo "Backup completed: $DATE"
```

```bash
sudo chmod +x /usr/local/bin/backup-teren.sh

# Add to crontab
crontab -e
```

Add:
```
0 2 * * * /usr/local/bin/backup-teren.sh >> /var/log/backup.log 2>&1
```

---

## Troubleshooting

### Container Won't Start

```bash
# Check logs
docker compose logs app

# Check container status
docker compose ps

# Rebuild container
docker compose down
docker compose build --no-cache app
docker compose up -d
```

### Permission Errors

```bash
# Fix storage permissions
docker compose exec app chown -R www:www /var/www/storage
docker compose exec app chmod -R 775 /var/www/storage
```

### Database Connection Issues

```bash
# Check if PostgreSQL is running
docker compose ps postgres

# Check PostgreSQL logs
docker compose logs postgres

# Test connection
docker compose exec app php artisan tinker
# In tinker: DB::connection()->getPdo();
```

### Queue Not Processing

```bash
# Check supervisor status
docker compose exec app supervisorctl status

# Restart queue workers
docker compose exec app supervisorctl restart all

# Check worker logs
docker compose exec app tail -f storage/logs/worker.log
```

# Check kernel module
lsmod | grep wireguard

# Check WireGuard interface
docker compose exec wireguard wg show
```

### Can't Access WireGuard Dashboard

```bash
# Check if container is running
docker compose ps wireguard

# Check logs
docker compose logs wireguard

# Verify port binding
sudo netstat -tulpn | grep 51821

# Try accessing via IP
curl http://YOUR_VPS_IP:51821
```

### Can't Access Application After VPN Connection

```bash
# Verify VPN connection
ping 10.13.13.1

# Check routing table (on client)
ip route | grep 10.13.13.0

# Check if services are bound correctly
docker compose exec app netstat -tulpn

# Check nginx logs
docker compose logs nginx

# Verify nginx is listening on VPN IP
docker compose exec nginx netstat -tulpn | grep 80

### SSL Certificate Issues

```bash
# Check certificate expiry
docker compose run --rm certbot certificates

# Renew manually
docker compose run --rm certbot renew

# Check nginx config
docker compose exec nginx nginx -t

# Reload nginx
docker compose restart nginx
```

### WireGuard Not Working

```bash
# Check WireGuard status
docker compose logs wireguard

# Restart WireGuard
docker compose restart wireguard

# Check firewall
sudo ufw status

# Verify port is open
sudo ss -tulpn | grep 51820
```

### High Memory Usage

```bash
# ChecWireGuard VPN configured and working
- [ ] WireGuard UI secured (VPN-only after initial setup)
- [ ] All services bound to VPN network (10.13.13.1)
- [ ] Firewall configured (UFW) - only VPN port public
- [ ] SSH key authentication enabled
- [ ] Strong passwords for all services (DB, pgAdmin, Portainer, WireGuard)
- [ ] `.env` file not in git
- [ ] SSL certificates configured (self-signed or Let's Encrypt)
- [ ] Regular backups automated
- [ ] Log rotation configured
- [ ] Security headers in nginx
- [ ] Docker containers run as non-root
- [ ] Regular system updates scheduled
- [ ] WireGuard client configs secur
### Application Returns 500 Error

```bash
# Check Laravel logs
docker compose exec app tail -f storage/logs/laravel.log

# Check permissions
docker compose exec app ls -la storage/

# Clear caches
docker compose exec app php artisan cache:clear
docker compose exec app php artisan config:clear
docker compose exec app php artisan route:clear
docker compose exec app php artisan view:clear
```

---

## Security Checklist

- [ ] Firewall configured (UFW)
- [ ] SSH key authentication enabled
- [ ] Strong database passwords
- [ ] `.env` file not in git
- [ ] Services behind WireGuard VPN
- [ ] SSL certificates valid
- [ ] Regular backups automated
- [ ] Log rotation configured
- [ ] Security headers in nginx
- [ ] Docker containers run as non-root
- [ ] Regular system updates scheduled

---

## Useful Commands Reference

```bash
# Deploy new version
./deploy.sh

# View all logs
docker compose logs -f

# Restart everything
docker compose restart

# Update single container
docker compose up -d --no-deps --build app

# Run artisan commands
docker compose exec app php artisan [command]

# Access container shell
docker compose exec app sh

# Database backup
docker compose exec postgres pg_dump -U teren_user teren_app > backup.sql

# System monitoring
htop
docker stats
df -h
```

---

## Support & Updates

For issues specific to the Teren App, check the application logs and supervisor status. For Docker/infrastructure issues, check container logs and system logs.

To update the deployment guide or Docker configuration, submit changes via Gitea and they'll be automatically deployed.

---

**Last Updated:** January 2026
**Version:** 1.0.0