high-tea v1.1.0

High Tea

Self-hosted full-stack Gitea service designed for use with Traefik.

Features

• Simple, consistent and deterministic way to create Gitea.
• Extremely flexible, powerful and self-configuring solution.
• Automatic, production-ready wildcard SSL certs with auto-renewal.
• Real-time dashboard showing service configuration and health metrics.
• Production-ready with support for organizations, mirrors and more.
• Add and remove services on-the-fly using familiar Docker commands.

Demo

A live demo of Gitea running under High Tea may be found at git.habd.as. Feel free to create an account to try it out.

Screenshots

Requirements

• Domain. Pick one up on Namecheap.
• Virtual Private Server. Get one with Vultr or DigitalOcean.

Basic Usage

Start the stack daemonized with docker-compose up -d. View the logs with docker-compose logs. Restart with restart and stop to stop.

Installation

1. Follow the Traefik Let's Encrypt Networking guide.
2. Copy this repository to the host machine.
3. Set traefik.frontend.rule in docker-compose.yml for your domain.
4. Start the stack with docker compose up -d.
5. Navigate to the host machine in a browser.
6. Access /install and complete initial configuration.

Initial Configuration

Select PostgreSQL as the database type. Use db as the host and set the user, password and database name using environment variables.

Defaults in docker-compose.yml:

POSTGRES_USER=gitea
POSTGRES_PASSWORD=gitea
POSTGRES_DB=gitea

Under General Settings set Site Title, SSH Server Domain and Gitea Base URL. These can be changed later in the Gitea app.ini config file.

Configure the admin user under the Administrator Account Settings then Install Gitea to complete initial configuration.

Using the Dark Theme

To use the dark theme modify app.ini as specified in Customizing the look of Gitea then restart Gitea with docker-compose restart gitea.

Accessing via SSH

Until Traefik supports TCP SSH connections to Gitea are exposed directly from the container to the host on port 2222 using the ports setting in docker-compose.yml. While it's possible to bind from the container directly to port 22 on the host chances are your host already has an SSH daemon running on this port.

To automatically use port 2222 when using git to interact with the remote create a config file in ~/.ssh/ on your client and add Port like:

Host gitea git.example.com
    HostName git.example.com
    Port 2222
    IdentityFile ~/.ssh/gitea_rsa
    User exampleuser

Where git.example.com matches your host domain and someuser matches your Gitea username.

Configuring Email Registration

Email may be used to receive notifications and allow new users to sign-up without relying on a separate OAuth provider. Setup is optional.

Unless you already have a provider see Recommended Email Providers for Discourse and consider one of the providers listed.

1. Add your Gitea domain in Mailgun
2. Add the Mailgun-suggested DNS records to domain. Rather than waiting 24-48 hours for DNS propogation look for the button inside Mailgun to check manually from the Mailgun dashboard.
3. Edit your app.ini file to enable user registrations, email confirmations and set a noreply address. Look in the [services] section for this stuff and reference the Config Cheat Sheet for help.

4. In the [mailer] section set the following:

   ENABLED=true FROM=noreply@git.domain.example USE_SENDMAIL=false HOST=smtp.mailgun.org:587 USER=from-mailgun-dashboard PASSWD=from-mailgun-dashboard

Consider also setting the ENABLE_NOTIFY_EMAIL option while you’re in there, then save and exit app.ini and then restart the Gitea service.

Test emails can then be sent from the admin configuration settings.

Additional Configuration

See the Gitea Docs for additional configuration options. For support head over to the Gitea Forums.

Migration Tips

Moving off GitHub, GitLab or Bitbucket? If so, the following resources may come in handy during the move:

• Duplicating a repository
• Changing author info
• Changing the Author of a Single Tag

If you're coming from Gogs please see the Upgrade from Gogs documentation on the Gitea website.

Backup Gitea and Database

Backups in High Tea use the standard Gitea Backup procedure adjusted for use with Docker Compose as follows:

1. Shell into the Gitea service as described in Debugging.

2. Use gitea dump the create the backup archive within the container:

   /app/gitea/gitea dump -c /data/gitea/conf/app.ini

3. Exit the shell and use docker cp to copy the archive to the host:

   docker cp $(docker ps -qf "name=gitea"):/gitea-dump-1537778440.zip .

If your host machine does not, itself, have a backup process in place consider moving the backup archive to a cloud storage service such as Mega or Amazon S3 for safekeeping.

Upgrading Gitea

Upgrades require some downtime until Zero downtime upgrades are available. To upgrade Gitea to a new tagged release do:

1. Perform a Gitea & Database Backup before you get started.
2. Then modify the Gitea image tag in docker-compose[.dev].yml.
3. Test things out using the development YAML compose file, if desired.
4. Then see Upgrade Gitea Docker Compose for next steps.

Review the Gitea release notes for breaking changes or special procedures prior to upgrade. If you need to check for running processes you can see them from Gitea using the /admin/monitor URL. If you run into problems during the upgrade please comment on the upgrade thread or open an issue in the High Tea git repository.

Managing Disk Space

If you run out of disk space you may have some problems continuing to use Gitea or its LFS. If this is the case here are some tips to help you understand where your disk space is and how you can clean it up:

• Run df -h --total / to check your disk space
• Purge or archive old backups to reclaim space
• Identify the size of and clean-up your Docker overlay network
• Run "Garbage collect all repositories" from Gitea's Admin Dashboard
• Use the docker system prune -a -f to remove unused images, et cetera
• Look for log files you no longer need and archive and/or disable them
• Consider using docker-gc-cron to keep overhead to a minimum
• Look at simply adding more storage space

If you find docker's overlay network is taking up the lion's share of space and none of the above are viable options consider backing up your Gitea repo to a remote location using scp and review the docker roadmap on deletes. If space is really precious consider restoring under a new docker overlay network or looking into remote/elastic storage options.

Development

For development install configure Docker on your machine:

• Get started with Docker for Mac
• Get started with Docker for Windows

Configure your environment to use the dev config override:

export COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml

Run docker-compose up to start the app.

Debugging

Shell into running Gitea service using an interactive pseudo-TTY:

docker exec -it $(docker ps -qf "name=gitea") bash

Login to a running Postgres service as the postgres user:

docker-compose exec db psql -U postgres

View last 50 timestamped log entries and follow log updates for [service] defined in Compose file services:

docker-compose logs --tail 50 --follow --timestamps [service]

License

Copyright (C) 2018 Josh Habdas jhabdas@protonmail.com

This work is free. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See the COPYING file for more details.