# 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.

Source: https://zopanel.net/docs/app-gitea  
Updated: 2026-10-09

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

| Item | Value |
| --- | --- |
| Image | `gitea/gitea:28` |
| Memory limit | 512 MB, 1 CPU |
| Free disk to install | About 1.3 GB on the Docker disk the first time (the image plus 1 GB kept free for the server), plus room for your repositories |
| Docker | Installed on the server (**App Store → Install Docker**) |
| Domain | A domain or subdomain whose A record points to the server, for example `git.example.com` |

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:

| Variable | Value | Effect |
| --- | --- | --- |
| `GITEA__server__ROOT_URL` | `https://<domain>/` | Public address used for links and HTTPS clone URLs |
| `GITEA__server__DOMAIN` | your domain | Server domain |
| `GITEA__server__DISABLE_SSH` | `true` | Turns Gitea's SSH server off, so only HTTPS clone URLs are shown (see [Clone and push](#clone-and-push)) |
| `GITEA__database__DB_TYPE` | `sqlite3` | Gitea uses a built-in SQLite database |

### 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](/docs/packages-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:

```bash
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

| Destination | Allowed? |
| --- | --- |
| Git hosts and APIs on the internet (migrations, mirrors, webhooks) | Yes |
| Websites on this server through their public domain (80/443) | Yes |
| Mail on this server (25, 465, 587) | Yes |
| MariaDB, PostgreSQL, Redis, SSH or the panel on this server | **No** |
| Private networks (10.x, 172.16–31.x, 192.168.x, 100.64.x), loopback | **No** |

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>`.

| Path on the server | Content |
| --- | --- |
| `…/<instance>/data/git/repositories/` | Bare Git repositories |
| `…/<instance>/data/gitea/gitea.db` | SQLite database: users, issues, pull requests, settings |
| `…/<instance>/data/gitea/conf/app.ini` | Gitea's configuration |
| `…/<instance>/data/` (rest) | Attachments, avatars, LFS objects, packages |

**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):

```bash
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](/docs/updating).

## Troubleshooting

| Symptom or message | What to do |
| --- | --- |
| Visitors see "This app is being set up" | Click **Setup finished — open to everyone** on the **Docker** tab. |
| `git push` fails with `HTTP 413` or "the remote end hung up unexpectedly" on a big push | The push is over the website's upload size (256 MB by default). Raise **Maximum upload (MB)** on the website's **Tools** tab → **Upload size** (up to 10 GB), or push in smaller parts. |
| `ssh: connect to host … port 22` asks for a server password or is refused | SSH clone is not available. Use the HTTPS URL. |
| HTTPS push asks for a password again and again with two-factor authentication on | Use an access token as the password. |
| Clone URLs show `http://` or a wrong domain | Check **Gitea Website URL** (`ROOT_URL`). ZoPanel sets it to `https://<domain>/` at every start. |
| A webhook or mirror to a private IP fails | Containers cannot reach private networks. Use a public address. |
| `Gitea needs 512 MB of memory; your plan has … MB and your apps use … MB` | Raise the package's **RAM (MB)** or remove another app. |
| `not enough disk space: this app needs about 1.3 GB free and the server has … GB; free some space first` | Free disk space, then install again. |
| Locked out of the admin account | As root: `docker exec -u git zp-app-<instance> gitea admin user change-password --username <name> --password '<new password>'`. |

## Related

- [App Store and S3 storage](/docs/apps)
- [What each app does](/docs/app-catalog)
- [Git deploy](/docs/git-deploy)
- [Packages and limits](/docs/packages-limits)
- [Gitea documentation](https://docs.gitea.com), [Backup and restore](https://docs.gitea.com/administration/backup-and-restore) and [configuration cheat sheet](https://docs.gitea.com/administration/config-cheat-sheet)