Self-hosted full-stack Gitea service designed for use with Traefik.
- 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.
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.
|Traefik Health Dashboard||Gitea Dashboard||Mailgun Email Logs|
- Follow the Traefik Let's Encrypt Networking guide.
- Copy this repository to the host machine.
docker-compose.ymlfor your domain.
- Start the stack with
docker compose up -d.
- Navigate to the host machine in a browser.
/installand complete initial configuration.
PostgreSQL as the database type. Use
db as the host and set the user, password and database name using environment variables.
Under General Settings set
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
Host gitea git.example.comHostName git.example.comPort 2222IdentityFile ~/.ssh/gitea_rsaUser exampleuser
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.
Add your Gitea domain in Mailgun
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.
app.inifile 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.
[mailer]section set the following:
ENABLED=true FROMfirstname.lastname@example.org 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.
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:
Shell into the Gitea service as described in Debugging.
gitea dumpthe create the backup archive within the container:/app/gitea/gitea dump -c /data/gitea/conf/app.ini
Exit the shell and use
docker cpto 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.
Upgrades require some downtime until Zero downtime upgrades are available. To upgrade Gitea to a new tagged release do:
- Perform a Gitea & Database Backup before you get started.
- Then modify the Gitea
- Test things out using the development YAML compose file, if desired.
- 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:
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 -fto 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.
For development install configure Docker on your machine:
Configure your environment to use the dev config override:
docker-compose up to start the app.
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
docker-compose exec db psql -U postgres
View last 50 timestamped log entries and follow log updates for
[service] defined in Compose file
docker-compose logs --tail 50 --follow --timestamps [service]
Copyright (C) 2018 Josh Habdas email@example.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.