Gitea

Install Gitea from the App Store, complete the Initial Configuration behind the setup lock, clone and push over HTTPS, back up repositories and update Gitea.

Updated Oct 9, 2026 · 9 min read

Gitea is a lightweight, self-hosted Git service, similar to GitHub or GitLab: private and public repositories, issues, pull requests, wikis, releases and a package registry, with a web interface. Choose it when a team or a solo developer wants code hosting under their own control without per-seat fees. This page covers installing Gitea from the App Store, the first-time configuration, how to clone and push from a ZoPanel container, backups and updates.

Requirements

Repositories are stored on the server's disk, outside the hosting account's home folder, so they do not count toward the account's disk quota. Keep an eye on free space.

Install Gitea

As an administrator

1. Open App Store. If you see Docker is required, click Install Docker first.

2. On the Gitea card, click Install.

3. Fill in the dialog:

   Field	What to enter
   Domain	The domain the app answers on, without http://. A new website is created for it.
   Owner	The hosting account the app belongs to. Its package limits apply to the container.
   Free SSL (Let's Encrypt)	Leave on. The certificate is issued at the end of the install if the domain points to the server.

4. Click Install and follow the task log until Gitea is available at http://<domain>.

5. If the log says SSL could not be issued yet, point the domain to the server and click Issue certificate on the website's SSL tab.

Gitea has no extra install fields. ZoPanel sets these variables, which Gitea applies to its app.ini on every start:

As a customer

Customers install from App Store in their own panel when the package allows it. Gitea needs 512 MB of the package's RAM (MB) and one slot of Packages → Docker apps. See Packages and limits.

First-time setup

A new install is behind a setup lock: until Gitea is configured, the first visitor could create its administrator, so ZoPanel shows everyone else "This app is being set up" until you finish.

1. Open the website and go to the Docker tab. Wait until the status is running.
2. In the Setup lock is on card, click Open the app (only for me). The Initial Configuration page opens.
3. Database Settings are already filled in with SQLite3. Leave them as they are.
4. In General Settings, set a Site Title. Check that Server Domain is your domain and Gitea Website URL is https://<domain>/.
5. SSH Server Port: nothing to change. ZoPanel turns Gitea's SSH server off, so Gitea shows HTTPS clone URLs only.
6. Optional, under Email Settings: enter an SMTP server so Gitea can send notifications and password resets. A mailbox created in the panel works: SMTP Host = your mail server name, SMTP Port 587 or 465, Send Email As, SMTP Username (the full address) and SMTP Password.
7. Under Server and Third-Party Service Settings, tick Only administrators can create user accounts (no self-registration) unless you want public sign-up. Tick Require sign-in to view pages for a private instance.
8. Under Administrator Account Settings, enter Administrator Username, Email Address, Password and Confirm Password.
9. Click Install Gitea. Gitea writes its configuration and signs you in.
10. Back on the Docker tab, click Setup finished — open to everyone.

Essential settings

• Two-factor authentication: your avatar → Settings → Security → Two-Factor Authentication (TOTP).
• Users: Site Administration → User Accounts to create accounts when self-registration is off.
• Access tokens: Settings → Applications → Generate New Token. With two-factor authentication on, Git over HTTPS needs a token instead of your password.
• To change a setting that is not in the web interface, edit /var/lib/zopanel-apps/<instance>/data/gitea/conf/app.ini as root and click Restart on the Docker tab. The four variables above are re-applied at every start and override the same keys in app.ini.

Clone and push

Use HTTPS:

git clone https://git.example.com/alice/website.git

Git asks for your Gitea user name and password (or an access token). To avoid typing it every time, use a credential helper, for example git config --global credential.helper store on a private machine.

Limits to know:

• SSH is not available. Port 22 of the server is the server's own SSH service, not Gitea's, so ZoPanel turns Gitea's SSH server off and clone URLs use HTTPS. A Gitea installed before ZoPanel set this keeps its old settings until it is reinstalled (Update to latest reuses the settings from the install); if it shows SSH clone URLs, set DISABLE_SSH = true in the [server] section of app.ini and restart to hide them.
• Each push request is limited by the website's upload size (256 MB by default). A larger push fails with HTTP 413. For big pushes, raise Maximum upload (MB) on the Gitea website's Tools tab → Upload size card (up to 10 GB). Alternatively, push a large history in several parts (for example branch by branch or a range of commits at a time), and keep large binaries in Git LFS files under that size.

What the container can reach

For Gitea this means:

• Migrate Repository and pull mirrors from GitHub, GitLab or another public host work.
• Webhooks to public URLs, including your own websites on this server by domain, work. Webhooks to private addresses fail.
• Gitea Actions needs a separate runner (act_runner) with its own Docker. ZoPanel does not provide one; a runner on another machine can connect to Gitea over HTTPS.

Where data lives and backups

The app's data is in /var/lib/zopanel-apps/<instance>/, where <instance> is the domain with dots replaced by hyphens (git.example.com → git-example-com). The container is zp-app-<instance>.

What ZoPanel backs up and what it does not: the Backups card on the website's Docker tab backs up the app's whole folder. Account backups and incremental backups cover website folders, databases and mailboxes of the account. They do not include /var/lib/zopanel-apps, so repositories and issues are only in the app's own backups. The configuration backup (.zpb) holds the panel's record of the app, not its data.

To back up Gitea, click Back up now on the Backups card of the website's Docker tab. Administrators can also set a Schedule (Off, Every day or Every week; off by default) and how many copies to Keep (1–60, default 7), then click Save. Each backup archives /var/lib/zopanel-apps/<instance>/ into /var/backups/zopanel-apps/<instance>/YYYYMMDD-HHMMSS.tar.gz, a folder only root can read that does not count toward the account's disk quota. The container is paused (not stopped) for the few seconds of the copy, so the SQLite database and repositories are consistent. Older copies beyond Keep are removed, and a failed scheduled backup sends administrators the Backup failed alert.

To restore, an administrator clicks Restore next to a backup. Gitea is stopped and its data replaced with the archive; the current data is kept aside until the restored app starts, and put back if it does not. Changes made since the backup are lost. Each backup also has a delete button (administrators only), and deleting the app together with its files deletes its backups too. Customers can click Back up now and see the list; the schedule and restores are done by the provider.

The archives stay on the same server. Copy important ones off it (for example with scp or rclone from /var/backups/zopanel-apps/<instance>/) and store them encrypted, since they contain Gitea's database and secrets. To restore on another server, install Gitea on the same domain there, copy the archive into /var/backups/zopanel-apps/<instance>/ on the new server and click Restore on its Backups card.

A portable archive with Gitea's own gitea dump (database as SQL, repositories, data and configuration):

docker exec -u git zp-app-git-example-com /usr/local/bin/gitea dump -c /data/gitea/conf/app.ini --file /tmp/gitea-dump.zip
docker cp zp-app-git-example-com:/tmp/gitea-dump.zip /root/gitea-dump-$(date +%F).zip
docker exec zp-app-git-example-com rm /tmp/gitea-dump.zip

Gitea's documentation recommends stopping activity while dumping for a fully consistent result; run it at a quiet time. Every clone is also a full copy of a repository's history, but not of issues, pull requests or wikis' metadata.

Update Gitea

1. Take a backup (Back up now on the Backups card). Gitea migrates its database on start; going back to an older version is not supported.
2. On the Docker tab, click Update to latest (administrators only; customers ask their provider).
3. The task pulls the catalog image and recreates the container. Repositories and settings are kept.

The catalog tag 28 follows Gitea's 28.x line, so Update to latest brings the newest 28.x release. Later major versions come with a ZoPanel update.

Troubleshooting

Related

• App Store and S3 storage
• What each app does
• Git deploy
• Packages and limits
• Gitea documentation, Backup and restore and configuration cheat sheet