Skip to content
Klutch.sh Docs

Deploying Gogs

Introduction

Gogs (Go Git Service) is a painless, self-hosted Git service written in Go. It’s designed to be lightweight, easy to install, and simple to use. Gogs provides a GitHub-like web interface for managing Git repositories, making it an excellent choice for individuals, teams, and organizations who want to host their own Git repositories without the complexity of larger solutions.

Gogs stands out for its:

  • Lightweight Design: Minimal system requirements with low memory and CPU usage
  • Easy Installation: Simple setup process with minimal dependencies
  • Cross-Platform: Runs on Windows, macOS, Linux, and ARM
  • Fast Performance: Written in Go for optimal speed and efficiency
  • GitHub-Like Interface: Familiar web UI for repository management
  • Self-Hosted Control: Complete ownership of your code and data
  • Active Development: Regular updates and an active community
  • Multiple Database Support: Works with SQLite, MySQL, PostgreSQL, and more

This comprehensive guide walks you through deploying Gogs on Klutch.sh using Docker, including detailed installation steps, sample configurations, database setup, persistent storage configuration, and production-ready best practices.

Prerequisites

Before you begin, ensure you have the following:

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your Gogs deployment project:

Terminal window
mkdir gogs-klutch
cd gogs-klutch
git init

Step 2: Create the Dockerfile (SQLite - Development)

Create a Dockerfile in your project root directory for a quick development setup using SQLite:

FROM gogs/gogs:latest


# Set working directory
WORKDIR /data


# Expose the default Gogs HTTP port
EXPOSE 3000


# Expose the SSH port for Git operations
EXPOSE 22


# The official Gogs image includes an entrypoint
# Data will be stored in /data (mount as volume)

Note: This minimal Dockerfile uses the official Gogs image with SQLite for quick testing. For production deployments, see the PostgreSQL or MySQL configuration below.

Step 3: Production Dockerfile with Database Support

For a production-ready setup, create a Dockerfile that’s optimized for external database connections:

FROM gogs/gogs:0.13.0


# Set environment for production
ENV USER=git
ENV GOGS_CUSTOM=/data/gogs


# Create necessary directories
RUN mkdir -p /data/git /data/gogs/conf /data/gogs/log


# Expose HTTP port
EXPOSE 3000


# Expose SSH port for Git operations
EXPOSE 22


# Volume for persistent data
VOLUME ["/data"]


# The official Gogs image includes the correct entrypoint
# No need to override it

Step 4: Create Configuration Template

Create an app.ini.example file to document the configuration structure:

[server]
PROTOCOL         = http
DOMAIN           = example-app.klutch.sh
ROOT_URL         = https://example-app.klutch.sh/
HTTP_PORT        = 3000
DISABLE_SSH      = false
SSH_PORT         = 22
OFFLINE_MODE     = false


[database]
DB_TYPE  = postgres
HOST     = postgres-app.klutch.sh:8000
NAME     = gogs
USER     = gogs
PASSWD   = your-secure-password


[repository]
ROOT = /data/git/gogs-repositories


[security]
INSTALL_LOCK = false
SECRET_KEY   = change-this-to-a-random-string


[service]
REGISTER_EMAIL_CONFIRM = false
ENABLE_NOTIFY_MAIL     = false
DISABLE_REGISTRATION   = false
ENABLE_CAPTCHA         = true
REQUIRE_SIGNIN_VIEW    = false


[mailer]
ENABLED = false


[log]
MODE      = file
LEVEL     = Info
ROOT_PATH = /data/gogs/log


[session]
PROVIDER = file


[picture]
DISABLE_GRAVATAR        = false
ENABLE_FEDERATED_AVATAR = false

Security Note: Never commit actual passwords or secret keys to your repository. Use environment variables in the Klutch.sh dashboard.

Step 5: Create Environment Configuration

Create a .env.example file to document required environment variables:

Terminal window
# Gogs Configuration
GOGS_DOMAIN=example-app.klutch.sh
GOGS_ROOT_URL=https://example-app.klutch.sh/


# Database Configuration (PostgreSQL recommended for production)
GOGS_DB_TYPE=postgres
GOGS_DB_HOST=postgres-host:5432
GOGS_DB_NAME=gogs
GOGS_DB_USER=gogs
GOGS_DB_PASSWORD=your-secure-password-here


# Security
GOGS_SECRET_KEY=generate-a-random-secret-key-here


# SSH Configuration
GOGS_SSH_PORT=22
GOGS_DISABLE_SSH=false


# Optional: Email Configuration
GOGS_MAILER_ENABLED=false
GOGS_MAILER_HOST=smtp.example.com:587
GOGS_MAILER_USER=noreply@example.com
GOGS_MAILER_PASSWD=your-email-password

Step 6: Create Startup Script (Optional)

For advanced configuration, create a custom start.sh script:

#!/bin/bash
set -e


# Create config directory if it doesn't exist
mkdir -p /data/gogs/conf


# Generate app.ini from environment variables if it doesn't exist
if [ ! -f /data/gogs/conf/app.ini ]; then
    cat > /data/gogs/conf/app.ini <<EOF
[server]
PROTOCOL         = http
DOMAIN           = ${GOGS_DOMAIN:-localhost}
ROOT_URL         = ${GOGS_ROOT_URL:-http://localhost:3000/}
HTTP_PORT        = 3000
SSH_PORT         = ${GOGS_SSH_PORT:-22}
DISABLE_SSH      = ${GOGS_DISABLE_SSH:-false}


[database]
DB_TYPE  = ${GOGS_DB_TYPE:-sqlite3}
HOST     = ${GOGS_DB_HOST:-127.0.0.1:5432}
NAME     = ${GOGS_DB_NAME:-gogs}
USER     = ${GOGS_DB_USER:-root}
PASSWD   = ${GOGS_DB_PASSWORD}


[repository]
ROOT = /data/git/gogs-repositories


[security]
INSTALL_LOCK = false
SECRET_KEY   = ${GOGS_SECRET_KEY:-please-change-this}


[service]
DISABLE_REGISTRATION = false


[log]
MODE      = file
LEVEL     = Info
ROOT_PATH = /data/gogs/log
EOF
fi


# Start Gogs
exec /app/gogs/docker/start.sh /bin/s6-svscan /app/gogs/docker/s6/

Note: Make the script executable: chmod +x start.sh

Step 7: Test Locally (Optional)

Before deploying to Klutch.sh, test your Gogs setup locally:

Terminal window
# Build the Docker image
docker build -t my-gogs .


# Run with SQLite for quick testing
docker run -d \
  --name gogs-test \
  -p 3000:3000 \
  -p 2222:22 \
  -v gogs-data:/data \
  my-gogs


# View logs
docker logs -f gogs-test


# Access Gogs at http://localhost:3000


# Stop and remove when done
docker stop gogs-test
docker rm gogs-test
docker volume rm gogs-data

Step 8: Create Documentation

Create a README.md file with usage instructions:

# Gogs Git Service Deployment


Self-hosted Git service on Klutch.sh with Docker.


## Features


- Lightweight Git service
- Web-based repository management
- SSH and HTTP(S) Git access
- User and organization support
- Issue tracking
- Pull requests and code review
- Wiki for each repository
- Activity timeline


## Initial Setup


After deployment, visit your Gogs URL to complete the installation wizard:


1. Navigate to `https://example-app.klutch.sh`
2. Complete the installation form:
   - Database settings (pre-filled if using environment variables)
   - Repository root path: `/data/git/gogs-repositories`
   - Application URL: `https://example-app.klutch.sh`
   - Create admin account
3. Click "Install Gogs"


## Git Operations


### Clone via HTTPS

git clone https://example-app.klutch.sh/username/repository.git

### Clone via SSH

git clone ssh://git@example-app.klutch.sh:22/username/repository.git

## Admin Panel


Access the admin panel at: `https://example-app.klutch.sh/admin`

Step 9: Push to GitHub

Commit your Dockerfile and configuration files to your GitHub repository:

Terminal window
git add Dockerfile .env.example app.ini.example README.md
git commit -m "Add Gogs Dockerfile and configuration"
git remote add origin https://github.com/yourusername/gogs-klutch.git
git push -u origin main

Deploying to Klutch.sh

Now that your Gogs project is ready and pushed to GitHub, follow these steps to deploy it on Klutch.sh with persistent storage and proper configuration.

Deployment Steps

    1. Log in to Klutch.sh

      Navigate to klutch.sh/app and sign in to your account.

    2. Create a New Project

      Go to Create Project and give your project a meaningful name (e.g., “Gogs Git Service”).

    3. Create a New App

      Navigate to Create App and configure the following settings:

    4. Select Your Repository

      • Choose GitHub as your Git source
      • Select the repository containing your Dockerfile
      • Choose the branch you want to deploy (usually main or master)

    5. Configure Traffic Type

      • Traffic Type: Select HTTP (Gogs serves a web interface via HTTP)
      • Internal Port: Set to 3000 (the default port that Gogs listens on)

      Note: For SSH Git operations, Gogs also uses port 22 internally, but HTTP traffic is sufficient for the web interface.

    6. Set Environment Variables

      Add the following environment variables for your Gogs configuration:

      Required Variables:

      • GOGS_DOMAIN: Your Gogs domain (e.g., example-app.klutch.sh)
      • GOGS_ROOT_URL: Full URL to your Gogs instance (e.g., https://example-app.klutch.sh/)

      Database Variables (for PostgreSQL - recommended):

      • GOGS_DB_TYPE: postgres (or mysql, sqlite3)
      • GOGS_DB_HOST: PostgreSQL host with port (e.g., postgres-app.klutch.sh:8000)
      • GOGS_DB_NAME: Database name (e.g., gogs)
      • GOGS_DB_USER: Database username (e.g., gogs)
      • GOGS_DB_PASSWORD: Strong database password

      Security Variables:

      • GOGS_SECRET_KEY: Random secret key for session encryption (generate a long random string)

      Optional Variables:

      • GOGS_SSH_PORT: SSH port (default: 22)
      • GOGS_DISABLE_SSH: Set to true to disable SSH (default: false)
      • GOGS_DISABLE_REGISTRATION: Set to true to disable new user registration

      Security Note: Always use strong, unique passwords and secret keys for production deployments.

    7. Attach a Persistent Volume

      This is critical for ensuring your Git repositories and Gogs data persist across deployments:

      • In the Volumes section, click “Add Volume”
      • Mount Path: Enter /data (this is where Gogs stores all its data including repositories, configuration, and logs)
      • Size: Choose an appropriate size based on your expected repository storage needs (e.g., 10GB for small teams, 50GB+ for larger organizations)

      Important: Gogs requires persistent storage to maintain your repositories, user data, and configuration between container restarts.

    8. Configure Additional Settings

      • Region: Select the region closest to your users for optimal latency
      • Compute Resources: Choose CPU and memory based on your team size (minimum 512MB RAM recommended, 1GB+ for larger teams)
      • Instances: Start with 1 instance (scale horizontally as needed)

    9. Deploy Your Application

      Click “Create” to start the deployment. Klutch.sh will:

      • Automatically detect your Dockerfile in the repository root
      • Build the Docker image
      • Attach the persistent volume
      • Start your Gogs container
      • Assign a URL for external access

    10. Complete Initial Setup

      Once deployment is complete, you’ll receive a URL like example-app.klutch.sh. Navigate to this URL to complete the Gogs installation wizard:

      https://example-app.klutch.sh

      Follow the installation wizard to:

      • Verify database configuration
      • Set up the admin account
      • Configure basic settings
      • Complete the installation

Database Configuration

Gogs supports multiple database backends. Here’s how to configure each:

SQLite (Development Only)

SQLite is the simplest option and requires no additional setup, but it’s not recommended for production use with multiple users.

Configuration:

  • Set GOGS_DB_TYPE=sqlite3
  • No additional environment variables needed
  • Database file stored in /data/gogs/data/gogs.db

Pros:

  • No external database required
  • Zero configuration
  • Good for single-user or testing

Cons:

  • Limited concurrent access
  • Not suitable for teams
  • Slower with large repositories

PostgreSQL is the recommended database for production deployments due to its reliability and performance.

Setup Steps:

  1. Deploy a PostgreSQL instance on Klutch.sh (follow the PostgreSQL guide)

  2. Create a database and user for Gogs:

    CREATE DATABASE gogs;
    CREATE USER gogs WITH PASSWORD 'your-secure-password';
    GRANT ALL PRIVILEGES ON DATABASE gogs TO gogs;

  3. Configure Gogs environment variables:

    Terminal window
    GOGS_DB_TYPE=postgres
    GOGS_DB_HOST=postgres-app.klutch.sh:8000
    GOGS_DB_NAME=gogs
    GOGS_DB_USER=gogs
    GOGS_DB_PASSWORD=your-secure-password

Connection String Format:

postgres://gogs:password@postgres-app.klutch.sh:8000/gogs?sslmode=disable

MySQL/MariaDB

MySQL and MariaDB are also well-supported and offer excellent performance.

Setup Steps:

  1. Deploy a MySQL instance on Klutch.sh

  2. Create a database and user:

    CREATE DATABASE gogs CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER 'gogs'@'%' IDENTIFIED BY 'your-secure-password';
    GRANT ALL PRIVILEGES ON gogs.* TO 'gogs'@'%';
    FLUSH PRIVILEGES;

  3. Configure Gogs environment variables:

    Terminal window
    GOGS_DB_TYPE=mysql
    GOGS_DB_HOST=mysql-app.klutch.sh:8000
    GOGS_DB_NAME=gogs
    GOGS_DB_USER=gogs
    GOGS_DB_PASSWORD=your-secure-password

Important: Use utf8mb4 character set for full Unicode support including emojis.

Environment Variables Reference

Complete list of Gogs environment variables you can configure in Klutch.sh:

VariableDescriptionRequiredDefault
GOGS_DOMAINDomain name for Gogs instanceYeslocalhost
GOGS_ROOT_URLFull URL including protocolYeshttp://localhost:3000/
GOGS_DB_TYPEDatabase type (sqlite3, postgres, mysql)Nosqlite3
GOGS_DB_HOSTDatabase host and portNo*127.0.0.1:5432
GOGS_DB_NAMEDatabase nameNo*gogs
GOGS_DB_USERDatabase usernameNo*root
GOGS_DB_PASSWORDDatabase passwordNo*Empty
GOGS_SECRET_KEYSecret key for encryptionYesRandom
GOGS_SSH_PORTSSH port for Git operationsNo22
GOGS_DISABLE_SSHDisable SSH accessNofalse
GOGS_DISABLE_REGISTRATIONDisable new user registrationNofalse
GOGS_REQUIRE_SIGNINRequire login to view pagesNofalse
GOGS_MAILER_ENABLEDEnable email notificationsNofalse
GOGS_MAILER_HOSTSMTP host and portNo*Empty
GOGS_MAILER_USERSMTP usernameNo*Empty
GOGS_MAILER_PASSWDSMTP passwordNo*Empty

*Required when using external database or email features

Git Operations

After your Gogs instance is deployed, you can perform all standard Git operations:

Creating a Repository

  1. Log in to your Gogs web interface
  2. Click the ”+” icon in the top right
  3. Select “New Repository”
  4. Fill in repository details and click “Create Repository”

Cloning via HTTPS

Terminal window
git clone https://example-app.klutch.sh/username/repository.git
cd repository

Cloning via SSH

For SSH access, configure your SSH key first in Gogs settings, then:

Terminal window
git clone ssh://git@example-app.klutch.sh:22/username/repository.git
cd repository

Pushing Changes

Terminal window
git add .
git commit -m "Your commit message"
git push origin main

Adding SSH Keys

  1. Generate SSH key (if you don’t have one):

    Terminal window
    ssh-keygen -t ed25519 -C "your-email@example.com"

  2. Copy your public key:

    Terminal window
    cat ~/.ssh/id_ed25519.pub

  3. Add to Gogs:

    • Navigate to Settings → SSH Keys
    • Click “Add Key”
    • Paste your public key
    • Click “Add Key”

Production Best Practices

Security Recommendations

  • Strong Passwords: Use a password manager to generate strong, random passwords for database and admin accounts
  • Secret Key: Generate a long, random secret key using: openssl rand -base64 64
  • HTTPS Only: Klutch.sh provides HTTPS by default; ensure GOGS_ROOT_URL uses https://
  • Disable Registration: After creating necessary accounts, set GOGS_DISABLE_REGISTRATION=true to prevent unauthorized signups
  • Regular Backups: Implement a backup strategy for your Git repositories using volume snapshots
  • Update Regularly: Keep Gogs updated to the latest version for security patches
  • Use External Database: PostgreSQL or MySQL instead of SQLite for production
  • Enable 2FA: Configure two-factor authentication for admin accounts
  • Restrict Admin Panel: Limit access to the admin panel to trusted users only

Performance Optimization

  • Database Indexing: Ensure your database has proper indexes (automatic with PostgreSQL/MySQL)
  • Repository Size: Monitor repository sizes and implement size limits if necessary
  • Cache Configuration: Gogs includes built-in caching; ensure it’s properly configured
  • Resource Allocation: Monitor CPU and memory usage and scale accordingly
  • Git LFS: Consider enabling Git Large File Storage for repositories with large binary files
  • Horizontal Scaling: For large teams, scale horizontally behind a load balancer

Monitoring and Maintenance

Monitor your Gogs deployment for:

  • Response Times: Ensure Git operations and web interface are responsive
  • Storage Usage: Watch repository storage growth and volume capacity
  • Memory Usage: Gogs should use minimal memory; monitor for memory leaks
  • Database Performance: Monitor database query performance and connection pool
  • Error Logs: Check /data/gogs/log for errors or warnings
  • User Activity: Review admin logs for suspicious activity

Data Management

  • Regular Backups: Create automated backups of /data volume
  • Repository Archives: Export important repositories periodically
  • Database Dumps: For external databases, schedule regular dumps
  • Retention Policies: Define data retention policies for old repositories
  • Migration Testing: Test your backup and restore procedures regularly

Email Configuration

For production use, configure email notifications:

Terminal window
GOGS_MAILER_ENABLED=true
GOGS_MAILER_HOST=smtp.gmail.com:587
GOGS_MAILER_USER=your-email@gmail.com
GOGS_MAILER_PASSWD=your-app-password
GOGS_MAILER_FROM=noreply@example.com

Email enables:

  • User registration confirmation
  • Password reset
  • Repository notifications
  • Issue and pull request updates

Advanced Configuration

Custom Configuration File

For advanced settings not covered by environment variables, create a custom app.ini:

  1. Create a custom configuration:

    Terminal window
    mkdir -p custom/conf
    nano custom/conf/app.ini

  2. Add custom settings (example):

    [repository.upload]
    ENABLED = true
    ALLOWED_TYPES =
    FILE_MAX_SIZE = 50
    MAX_FILES = 5
    

    [attachment]
    ENABLED = true
    MAX_SIZE = 4
    MAX_FILES = 5
    

    [picture]
    DISABLE_GRAVATAR = false
    

    [webhook]
    QUEUE_LENGTH = 1000
    DELIVER_TIMEOUT = 5

  3. Mount the custom directory as a volume in your Dockerfile

Using Git LFS

To enable Git Large File Storage:

  1. Install Git LFS in your Dockerfile:

    RUN apk add --no-cache git-lfs

  2. Configure in app.ini:

    [server]
    LFS_START_SERVER = true
    LFS_CONTENT_PATH = /data/git/lfs

Webhook Configuration

Gogs supports webhooks for CI/CD integration:

  1. Navigate to Repository Settings → Webhooks
  2. Click “Add Webhook”
  3. Choose webhook type (Gogs, Slack, Discord, etc.)
  4. Enter payload URL
  5. Select events to trigger webhook
  6. Click “Add Webhook”

Backup Automation

Create a backup script:

#!/bin/bash
BACKUP_DIR="/backup"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)


# Backup Git repositories
tar -czf $BACKUP_DIR/gogs-repos-$TIMESTAMP.tar.gz /data/git


# Backup Gogs data
tar -czf $BACKUP_DIR/gogs-data-$TIMESTAMP.tar.gz /data/gogs


# Backup database (if using PostgreSQL)
pg_dump -h $GOGS_DB_HOST -U $GOGS_DB_USER $GOGS_DB_NAME > $BACKUP_DIR/gogs-db-$TIMESTAMP.sql


# Remove backups older than 30 days
find $BACKUP_DIR -name "gogs-*" -mtime +30 -delete

Troubleshooting

Cannot Access Gogs Web Interface

  • Verify your app is running in the Klutch.sh dashboard
  • Check that the internal port is set to 3000
  • Ensure HTTP traffic type is selected
  • Review application logs for startup errors
  • Verify GOGS_ROOT_URL matches your actual URL

Database Connection Errors

  • Verify database credentials are correct
  • Check database host is accessible from Gogs container
  • Ensure database exists and user has proper permissions
  • For PostgreSQL, verify port 8000 is used (Klutch.sh default for TCP traffic)
  • Test database connection separately

Git Push/Pull Fails

  • Check SSH keys are properly added to Gogs
  • Verify repository permissions for the user
  • Ensure /data/git has sufficient space
  • Check Git URL format is correct
  • Review Gogs logs for detailed error messages

SSH Access Not Working

  • Verify GOGS_DISABLE_SSH is not set to true
  • Check SSH port configuration matches your setup
  • Ensure SSH keys are added to your Gogs user profile
  • Test SSH connection: ssh -T git@example-app.klutch.sh -p 22
  • Review Gogs SSH logs

Data Not Persisting

  • Confirm the persistent volume is attached at /data
  • Check the volume has sufficient space
  • Verify Gogs is writing to the correct directory
  • Review volume mount configuration in Klutch.sh

Performance Issues

  • Monitor CPU and memory usage in Klutch.sh dashboard
  • Check database query performance
  • Review repository sizes for large repos
  • Consider increasing compute resources
  • Enable caching if not already active

Installation Wizard Keeps Appearing

This means INSTALL_LOCK is not set:

  • Complete the installation wizard properly
  • Ensure /data volume is persistent
  • Check that /data/gogs/conf/app.ini exists and has INSTALL_LOCK = true

Migrating from GitHub/GitLab

Gogs supports importing repositories from other Git services:

Import from GitHub

  1. In Gogs, click ”+” → “New Migration”
  2. Select “GitHub”
  3. Enter GitHub repository URL
  4. Provide GitHub access token (if private repo)
  5. Click “Migrate Repository”

Import from GitLab

  1. In Gogs, click ”+” → “New Migration”
  2. Select “GitLab”
  3. Enter GitLab repository URL
  4. Provide GitLab access token (if private repo)
  5. Click “Migrate Repository”

Bulk Migration

For bulk migrations, use the Gogs API:

Terminal window
curl -X POST https://example-app.klutch.sh/api/v1/repos/migrate \
  -H "Authorization: token YOUR_GOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clone_addr": "https://github.com/username/repo.git",
    "uid": 1,
    "repo_name": "migrated-repo"
  }'

Upgrading Gogs

To upgrade Gogs to a new version:

  1. Check the Gogs releases page for the latest version

  2. Update the version in your Dockerfile:

    FROM gogs/gogs:0.13.0

  3. Commit and push the changes:

    Terminal window
    git add Dockerfile
    git commit -m "Upgrade Gogs to version 0.13.0"
    git push

  4. Klutch.sh will automatically rebuild and redeploy your application

  5. Your data will be preserved in the persistent volume

  6. Review the release notes for any breaking changes or migration steps

Important: Always backup your data before upgrading, especially for major version changes.

Additional Resources

Conclusion

Deploying Gogs to Klutch.sh with Docker provides a lightweight, self-hosted Git service with full control over your code repositories. By following this guide, you’ve set up a production-ready Gogs instance with persistent storage, proper database configuration, and security best practices. Your Git service is now ready to host unlimited repositories for your team, with a familiar GitHub-like interface and powerful Git features, all while maintaining complete control over your source code and data.