Nefarious Plastic Mannequins

    high-tea

    1.1.0 • Public • Published

    High Tea

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

    Latest NPM version NPM downloads per month WTFPL licensed Telegram chat Keybase profile

    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

    Traefik Health Dashboard Gitea Dashboard Mailgun Email Logs
    Traefik Health Dashboard Gitea Dashboard Mailgun Email Logs

    Requirements

    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:

    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:

    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.

    Install

    npm i high-tea

    DownloadsWeekly Downloads

    1

    Version

    1.1.0

    License

    WTFPL

    Unpacked Size

    277 kB

    Total Files

    10

    Last publish

    Collaborators

    • jhabdas
    • vhsdev