gitea-docker/README.md

Gitea Docker Setup

This is a Docker Compose configuration for running Gitea with PostgreSQL, configured with HTTPS support.

Prerequisites

• Docker Desktop for Windows
• Docker Compose
• A domain or DDNS service (configured to point to your server)
• Port forwarding configured on your router (if accessing from outside your network)

Features

• Gitea with HTTPS support
• PostgreSQL database
• SSH access for Git operations
• Persistent data storage
• Self-signed SSL certificates (can be replaced with Let's Encrypt)
• Automated database backup system

Configuration

The setup includes:

• Gitea web interface:
  • External access: https://bee8333.ddns.net/
  • Local network access: https://bee8333.ddns.net/ or https://localhost:3000
  • Local development: https://127.0.0.1:3000
• SSH access on port 222 (for git clone/push/pull)
• PostgreSQL database (internal access only)
• SSL certificates in ./gitea/ssl/
• Persistent data storage for both Gitea and PostgreSQL

Access Methods

Web Interface

1. External Access (Internet):

   • URL: https://bee8333.ddns.net/
   • Requires port 3000 forwarded on your router
   • Uses HTTPS with SSL certificate

2. Local Network Access:

   • Same URL: https://bee8333.ddns.net/
   • Or use: https://localhost:3000
   • Both use HTTPS with SSL certificate
   • No port forwarding needed

3. Local Development:

   • URL: https://127.0.0.1:3000
   • Direct access on the hosting machine
   • Uses HTTPS with SSL certificate

Git Operations (SSH)

• External SSH URL: ssh://git@bee8333.ddns.net:222/username/repository.git
• Local SSH URL: ssh://git@localhost:222/username/repository.git
• Requires port 222 forwarded on your router for external access

Getting Started

1. Make sure Docker Desktop is running
2. Clone this repository
3. Open a terminal in this directory
4. Generate SSL certificates (see SSL Certificates section)
5. Run docker-compose up -d
6. Access Gitea using one of the URLs above
7. During first-time setup:
   • Database settings are pre-configured (no changes needed)
   • Domain is set to your domain name
   • SSH port is set to 222
   • HTTPS is enabled by default

SSL Certificates

You'll need to generate SSL certificates before starting the service. The certificates should be placed in ./gitea/ssl/:

• cert.pem - The SSL certificate
• key.pem - The private key

To generate self-signed certificates (for development/testing):

# Create the ssl directory
mkdir -p gitea/ssl

# Generate certificates using OpenSSL
docker run --rm -v ${PWD}/gitea/ssl:/ssl alpine/openssl req -x509 -nodes \
  -days 365 -newkey rsa:2048 \
  -keyout /ssl/key.pem -out /ssl/cert.pem \
  -subj "/CN=your.domain.here"

Replace your.domain.here with your actual domain name.

Security Notes:

• Never commit SSL certificates to version control
• Keep your private key (key.pem) secure
• For production use, consider using Let's Encrypt certificates
• Self-signed certificates will show browser security warnings

Backup System

This setup includes a comprehensive backup strategy to ensure your Gitea data is always protected. The backup system provides two complementary methods:

Database Backups

PowerShell scripts are included to manage database backups:

1. Creating Backups:

   powershell -ExecutionPolicy Bypass -File .\backup-gitea-db.ps1
   

   This creates a SQL dump of your PostgreSQL database, compressed as a ZIP file in the backups directory.

2. Volume Backups:

   powershell -ExecutionPolicy Bypass -File .\backup-volume.ps1
   

   This backs up the entire PostgreSQL data volume as a TAR archive, compressed as a ZIP file.

3. Automated Backups:

   powershell -ExecutionPolicy Bypass -File .\schedule-backup.ps1
   

   This creates a Windows Scheduled Task that runs database backups daily at 3 AM.

4. Restoring from Backups:

   # Restore from database dump
   powershell -ExecutionPolicy Bypass -File .\restore-gitea-db.ps1 -BackupFile "backups\your-backup-file.sql.zip"
   
   # Restore from volume backup
   powershell -ExecutionPolicy Bypass -File .\restore-volume.ps1 -BackupFile "backups\your-volume-backup.tar.zip"
   

Backup Best Practices

• Keep multiple backups using both methods (database dumps and volume backups)
• Store backups in multiple locations (local and off-site)
• Test restoring from backups periodically
• Create a backup before upgrading Gitea or making significant changes
• Never run docker-compose down -v unless you have a recent backup

For more detailed information about the backup system, see BACKUP-README.md.

Stopping the Services

To stop the services, run:

docker-compose down

Important: Do not use the -v flag (docker-compose down -v) unless you intend to delete all data, as this will remove the Docker volumes containing your database.

Data Persistence

All data is stored in Docker volumes and local directories:

• ./gitea/ - Gitea configuration and data
  • ./gitea/ssl/ - SSL certificates
  • ./gitea/conf/ - Gitea configuration
• Docker volumes (managed by Docker):
  • gitea-data - Gitea repositories and application data
  • postgres-data - PostgreSQL database files
• ./backups/ - Database and volume backups

Troubleshooting

1. Cannot access externally:

   • Verify port 3000 (HTTP) and 222 (SSH) are forwarded on your router
   • Check your DDNS service is updating correctly
   • Ensure your domain points to your correct IP

2. SSL Certificate Warnings:

   • This is normal with self-signed certificates
   • For production, consider using Let's Encrypt certificates

3. Local Network Access:

   • If bee8333.ddns.net doesn't resolve locally, use localhost:3000 instead
   • Add an entry to your hosts file if needed

4. Database Backup Issues:

   • Ensure Docker is running when attempting backups
   • Check that the container names match those in the backup scripts
   • For PowerShell execution issues, use the -ExecutionPolicy Bypass flag