You can self-host Gitea on a VoyraCloud VPS by selecting the preinstalled application image, creating the first administrator through SSH, and then using the web interface, HTTPS Git, or SSH Git for your repositories. The image removes the manual installation step, while account policy, domains, HTTPS, repository access, updates, backups, and incident response remain under your control.
TL;DR
- The VoyraCloud Gitea application image provides a preinstalled Gitea Community Edition instance on Cloud VPS and Residential IP VPS.
- The installation page is locked before delivery. Create the first administrator through the SSH command shown in your resource details, not through a publicly exposed installation wizard.
- Port
3000is bound to the VPS loopback interface. Use the SSH Tunnel command in the resource details for the first web login; it is not exposed as public HTTP. - Add a domain, reverse proxy, and browser-trusted HTTPS before publishing the web interface or using HTTPS Git. Gitea SSH Git uses the separate public port
2222after you add a public key to your account. - New-user registration is disabled by default. The administrator decides whether to create users manually or change the registration policy.
- Repositories, accounts, issues, pull requests, packages, attachments, configuration, and secrets persist across a normal VPS reboot, but reboot persistence is not an off-server backup.
- VoyraCloud does not automatically upgrade, back up, monitor, or administer the Gitea instance after delivery.
What Is Gitea?
Gitea is an open-source software development service for hosting Git repositories and collaborating on source code. It provides a web interface around standard Git workflows together with user accounts, organizations, repository permissions, pull requests, issues, projects, wikis, releases, packages, webhooks, and API access.
The official Gitea documentation describes installation and administration for teams that want to operate their own service. Self-hosting is useful when you want the repository service, storage location, account policy, network access, update timing, and backup process under your own administration.
A Gitea VPS is a practical fit for:
- A developer who wants private repositories on a personal server.
- A small team that needs Git hosting, code review, issues, and organization permissions.
- An agency that keeps separate repositories for client projects.
- An infrastructure team that connects repositories to deployment systems through SSH keys, access tokens, webhooks, or APIs.
- A lab or internal environment that needs a lightweight alternative to a larger software-development platform.
Self-hosting does not make repository operations maintenance-free. Someone still owns operating-system security, Gitea updates, authentication policy, HTTPS, backups, storage growth, abuse prevention, and recovery testing.
How Do You Start with the VoyraCloud Gitea Image?
The fastest deployment path is to create a supported VoyraCloud VPS with the Gitea image and run the private administrator-setup command from the resource details. You do not need to install Docker, Gitea, or the initial database manually.
- Open the VoyraCloud page for Gitea from the link above and continue to the VPS purchase flow.
- Select an eligible Cloud VPS or Residential IP VPS configuration. Cloud VPS is the general-purpose option for Git hosting; Residential IP VPS remains available when your wider workload specifically needs that product’s network characteristics.
- Choose any region currently offered by the selected VPS product and confirm that Gitea is selected in the Images section.
- Create the VPS and wait until the resource and application are ready.
- Open the resource details and locate the Application section.
- Copy the Admin Setup command. It follows this pattern:
ssh -t -p <ssh-port> <ssh-user>@<server-ip> 'sudo /usr/local/sbin/voyra-gitea-create-admin'7. Run the command from your terminal and enter the administrator username and email. Gitea’s official CLI generates a 24-character one-time random password and displays it only in the current SSH session.
8. Copy the SSH Tunnel command from the Application section and keep that terminal session open. It follows this pattern:
ssh -N -L 3000:127.0.0.1:3000 -p <ssh-port> <ssh-user>@<server-ip>9. Open the local access URL in your browser:
http://127.0.0.1:300010. Sign in with the administrator account and one-time password, then set a new password when Gitea requires the change.
11. Create a private test repository, add an SSH public key, and verify one SSH clone and push.
12. Connect your domain, configure trusted HTTPS, update the Gitea public URL settings, and confirm that generated HTTPS clone links use the intended address.
13. Restart the VPS once and verify that Gitea returns automatically with the administrator, test repository, commit history, keys, and settings intact.
14. Create an off-server backup and perform a test restore before relying on the instance for important source code.
The setup command is intentionally separate from the web page. The public installation wizard is already locked, so an internet visitor cannot claim a new instance by creating the first administrator before the owner does. The command also stops if an administrator already exists.
Use the SSH username and port shown for your VPS resource. Do not assume that every server uses root or port 22. The VPS SSH connection used for administration is also different from Gitea’s SSH Git endpoint on port 2222.
What Does the Application Image Include?
The Gitea application image includes a persistent single-server starting point, not a managed source-code hosting service. The delivery boundary determines what you must configure before regular team use.
| Delivered by the application image | User-managed or not included |
|---|---|
| Gitea Community Edition stable release approved for the image | Automatic Gitea upgrades |
| Ubuntu-based VPS environment | Managed operating-system administration |
| Gitea running in the official container with a local SQLite database | External PostgreSQL or MySQL service |
| Locked installation page | Public web installation wizard |
| Private SSH command for creating the first administrator | Precreated administrator or fixed password |
| Registration disabled by default | Automatic team-member provisioning |
Web backend on loopback port 3000 | Public HTTP exposure, domain registration, reverse proxy, and automatic HTTPS |
SSH Git on port 2222 | Preinstalled user SSH keys |
| Persistent repositories, database, configuration, and application data | Automatic off-server backups |
| Service recovery after a normal VPS restart | High availability or automatic failover |
| Standard Gitea collaboration features | Managed runners, CI capacity, SMTP, OAuth, LDAP, or external storage |
The image does not include sample repositories, organizations, users, runners, packages, third-party credentials, email delivery, a domain, or a browser-trusted certificate. It also does not expose application secrets in the resource details.
How Does Secure First-Administrator Setup Work?
The first administrator is created through an authenticated VPS SSH session, while Gitea’s public installation page remains locked. This prevents the common race in which an uninitialized web installer is reachable from the internet and an unintended visitor completes setup first.
The application image prepares the database and configuration before delivery. It enables Gitea’s installation lock and disables public user registration. The Admin Setup command then runs Gitea’s official administrative command inside the application environment.
The setup process should have these properties:
- It asks for the username and email interactively.
- It tells Gitea’s official CLI to generate a 24-character random password instead of placing your chosen password in a command-line argument.
- It shows the one-time password only in the current SSH terminal and does not write it to shell history, a file, or a log.
- It requires a password change on the first web login.
- It refuses to create another administrator after the first administrator exists.
- It does not generate a personal access token or SSH key for you.
- It does not print Gitea’s internal secrets.
After signing in, review Site Administration and the user-registration policy. Registration is off by default so that unknown internet users cannot create accounts. You can create approved users from the administration interface or change the policy if open registration is an intentional requirement and you have an abuse-control plan.
Do not send the one-time or final administrator password through chat, a ticket, or a shared shell transcript. Close the initial SSH session after changing the password. Add a second administrator only when operational ownership requires it, and use a separate normal account for routine Git work when practical.
How Do HTTPS Git and SSH Git Differ?
HTTPS Git uses the Gitea web endpoint behind your trusted HTTPS domain, while SSH Git uses a dedicated Gitea SSH service and an account-level public key. Both support normal clone, fetch, pull, and push operations, but their authentication and transport setup differ.
| Method | Initial address pattern | Authentication | Best use after setup |
|---|---|---|---|
| Initial web interface | http://127.0.0.1:3000 through SSH Tunnel | Gitea username and password | First login, password change, and private setup |
| Regular web interface | https://git.example.com | Gitea username and password | Repository browsing and administration after domain setup |
| HTTPS Git | https://git.example.com/<owner>/<repo>.git | Prefer a personal access token for Git clients | Web-based Git transport after domain and trusted HTTPS setup |
| SSH Git | ssh://git@<server-ip>:2222/<owner>/<repo>.git | SSH public key added to the Gitea account | Convenient for developer Git clients and automation using managed keys |
| VPS system SSH | Resource-specific host and port | VPS SSH key or current server credential | Server administration and first-admin setup, not repository access |
For SSH Git:
- Create or choose an SSH key on your workstation.
- Sign in to Gitea and add the public key under account settings.
- Copy the SSH clone address from the repository page.
- Verify the host fingerprint on first connection instead of accepting an unexpected key without checking it.
- Keep the private key on the client and protect it with appropriate file permissions and, when suitable, a passphrase.
Gitea SSH Git should not ask for the Gitea web password. Port 2222 belongs to the repository service; it does not provide a server shell.
For HTTPS Git, create a personal access token with only the permissions needed by that client or integration. Avoid putting a token directly into a command that will remain in shell history. Use your Git credential helper or a secret store appropriate to your operating system.
Why Should You Add a Domain and HTTPS?
A domain and browser-trusted HTTPS protect web credentials and HTTPS Git traffic and give the instance a stable public identity. The image keeps port 3000 on the VPS loopback interface, so the web service is not publicly reachable until you deliberately configure a reverse proxy.
The official Gitea reverse-proxy guide explains how Gitea operates behind common proxies. A production setup normally includes:
- A DNS record such as
git.example.compointing to the VPS. - A reverse proxy listening on ports
80and443. - A browser-trusted TLS certificate for the domain.
- An HTTP-to-HTTPS redirect.
- Forwarded host, client-address, and protocol headers that match the proxy configuration.
- Gitea’s public
ROOT_URLand domain settings updated to the final HTTPS URL. SSH_DOMAINand the displayed SSH port updated so repository clone instructions remain accurate.
After changing the address, verify all of the following:
- The sign-in page loads without a certificate warning.
- Links generated by Gitea use the HTTPS domain rather than the old IP address.
- HTTP Git clone and push work through HTTPS.
- SSH clone links show the correct domain and port.
- Webhooks and OAuth callback URLs, if later configured, use the intended public address.
- Large pushes do not fail because of reverse-proxy body or timeout limits.
The application image does not register the domain or issue the certificate for you. Those steps are user-managed because the final hostname and DNS account belong to the site owner.
How Should You Organize Users and Repository Access?
Use individual accounts, organization teams, repository permissions, SSH keys, and scoped tokens instead of sharing one administrator identity. Gitea can host private and public repositories, but the administrator must decide who can discover, read, write, review, and administer each resource.
A practical small-team baseline is:
- Keep public registration disabled unless there is a deliberate reason to open it.
- Give each person an individual account.
- Reserve administrator access for server and service owners.
- Create organizations for related repositories and teams for permission groups.
- Grant the least repository permission needed for each role.
- Use branch protection and review rules for important branches.
- Use deploy keys or scoped personal access tokens for automation rather than an administrator password.
- Remove accounts, keys, and tokens promptly when access is no longer required.
- Enable two-factor authentication for privileged users when it fits your access model.
- Review organization, repository, webhook, OAuth, and token ownership periodically.
If you later connect SMTP, OAuth, LDAP, or OpenID Connect, treat that as a separate production change. Test account linking, recovery, offboarding, administrator access, and failure behavior before relying on the integration. The base image does not include these services or their credentials.
What Must a Gitea Backup Protect?
A complete Gitea backup must protect the database, Git repositories, configuration, application secrets, and any attachments, LFS objects, packages, releases, avatars, or other stored data your instance uses. Copying only the Git repositories is not enough to reconstruct users, permissions, issues, pull requests, tokens, webhooks, and service settings.
The official Gitea backup and restore documentation describes the gitea dump workflow and warns that the service contains several data layers that can change together. A consistent backup requires coordination; an application database that says a repository operation completed while the repository copy captured an earlier state can produce an incomplete recovery point.
Your backup plan should define:
| Layer | Examples | Why it matters |
|---|---|---|
| Database | Users, permissions, issues, pull requests, settings, tokens | Recreates application state and relationships |
| Git repositories | Commits, branches, tags, Git objects | Preserves source history |
| Configuration and secrets | Public URL, service settings, SECRET_KEY, internal tokens | Keeps encrypted data readable and behavior consistent |
| Application data | Attachments, avatars, LFS, packages, release assets, indexes | Preserves content outside normal Git objects |
| Recovery procedure | Versions, ownership, hook regeneration, verification steps | Turns stored files into a usable restored service |
Store recovery copies outside the VPS. Encrypt them when they contain private source code, credentials, tokens, personal data, or internal configuration. Keep more than one recovery point, monitor backup completion, and test a restore on a separate environment.
A normal VPS reboot proves persistence, not recoverability. It does not protect against accidental deletion, repository corruption, a failed upgrade, credential compromise, filesystem loss, VPS deletion, or an attacker deleting both the live data and local backup files.
For the broader server-maintenance baseline around SSH, patching, monitoring, and recovery ownership, see VPS Management: Practical Guide.
How Should You Update Gitea?
Update Gitea as a controlled application change: read the release notes, create a restorable backup, preserve the deployment type, and verify repositories and authentication afterward. The image uses a fixed stable release rather than a floating tag so a restart does not silently change the application version.
Before an update:
- Read the Gitea release and upgrade notes for the source and target versions.
- Confirm the supported upgrade path instead of skipping across versions without review.
- Create and verify an off-server backup.
- Record the current container image, configuration, public URL, SSH settings, and storage ownership.
- Plan a maintenance window because database migrations or backup consistency may require downtime.
After an update:
- Confirm that the container reaches a healthy state.
- Sign in with a normal account and an administrator account.
- Clone, pull, and push through HTTP(S) and SSH.
- Open an issue and pull request in a test repository.
- Check webhooks, packages, LFS, email, and authentication integrations that your instance actually uses.
- Verify that generated clone URLs still use the correct domain and port.
- Confirm that users, repositories, configuration, and secrets survived the change.
Do not switch casually between Gitea’s rootful and rootless container layouts; the official Docker documentation notes that their storage and SSH behavior differ. Preserve the deployment model selected by the application image unless you have a migration and rollback plan.
How Much VPS Capacity Does Gitea Need?
Gitea capacity depends on user concurrency, repository count and size, Git operation patterns, packages, LFS, indexing, automation, and data-retention requirements. Choose an eligible plan in the purchase flow, monitor the real workload, and move to a larger configuration when sustained CPU, memory, disk, or I/O pressure appears.
The official Gitea project describes a small-team installation as relatively lightweight, but that statement does not define the capacity of every repository workload. Large monorepositories, frequent clones, large binary assets, package storage, search indexing, and automated jobs can change the resource profile substantially.
| Workload | Capacity consideration |
|---|---|
| A few small source repositories | Appropriate for an entry validation workload |
| Small development team | Measure concurrent web and Git operations |
| Large repository history | Plan for disk space, backup time, and clone traffic |
| Git LFS or package registry | Plan storage and transfer separately from normal Git objects |
| Many webhooks or integrations | Monitor queues, failures, and downstream availability |
| Gitea Actions | Runner capacity is separate and not included by the base image |
| External database or object storage | Requires a separately designed and operated architecture |
Watch memory pressure, CPU saturation, filesystem capacity, inode use, SQLite lock behavior, container restarts, request latency, failed Git operations, backup duration, and restore duration. The minimum purchase gate is a validated starting point, not a promise of unlimited repositories or users.
Common Mistakes to Avoid
Most early Gitea failures come from treating a preinstalled repository service as a fully managed platform. Avoid these mistakes:
- Leaving an installation wizard exposed. Use the SSH administrator-setup flow and keep the installation lock enabled.
- Opening public registration without an abuse plan. Keep registration disabled unless open signup is intentional.
- Exposing port
3000as public HTTP. Keep it on loopback and add a domain with trusted HTTPS before routine web and HTTPS Git use. - Confusing port
2222with VPS shell access. It is the Gitea SSH Git endpoint and does not provide a server shell. - Sharing one administrator account. Use individual accounts and least privilege.
- Putting tokens in shell history or repository files. Use an appropriate credential or secret store.
- Backing up only Git repositories. Protect the database, configuration, secrets, attachments, LFS, packages, and recovery procedure too.
- Keeping the only backup on the same VPS. Store encrypted recovery copies outside the server.
- Using a floating container tag. Pin the tested stable release and update deliberately.
- Assuming minimum capacity covers CI or large binaries. Runners, packages, LFS, monorepositories, and heavy concurrency require separate sizing.
- Changing the public URL without updating Gitea. Verify
ROOT_URL, domain, SSH domain, clone links, callbacks, and webhooks. - Updating without a restore test. A backup that has never been restored is an unverified recovery plan.
FAQ
Can I self-host Gitea without installing it manually?
Yes. The VoyraCloud Gitea application image provides a preinstalled Community Edition instance on an eligible Cloud VPS or Residential IP VPS. You still create the first administrator, configure repository access, connect a domain and HTTPS, manage users, and own updates and backups.
Why is the first administrator created through SSH?
SSH keeps the administrator-creation step behind access to the VPS and prevents an internet visitor from claiming an exposed installation wizard. The public installation page is locked before delivery, and the setup command refuses to create another administrator after one already exists.
Can I expose port 3000 directly to the internet?
No. The application binds port 3000 to the VPS loopback interface and the first login uses an SSH Tunnel. Connect a domain, configure a reverse proxy and browser-trusted HTTPS, and update Gitea’s public URL settings before publishing the web service.
What is the difference between VPS SSH and Gitea SSH Git?
VPS SSH administers the Linux server, while Gitea SSH Git transfers repository data using keys attached to Gitea accounts. The VPS uses the SSH host and port shown for the resource; Gitea SSH Git uses the git user and port 2222.
Should I use a password or token for HTTPS Git?
Use a personal access token with only the permissions needed by the client or integration. Store it in an appropriate credential helper rather than embedding it in a repository, script, or shell-history entry.
Is public user registration enabled?
No. The application image disables self-registration by default. The administrator can create approved users or deliberately change the registration policy after assessing abuse, email verification, and access-control requirements.
Does the image include Gitea Actions runners?
No. The base image does not provision or operate Actions runners. Runner execution capacity, isolation, secrets, network access, and maintenance require a separate design.
What must I back up?
Protect the database, Git repositories, configuration, application secrets, attachments, LFS objects, packages, releases, and any other stored application data. Keep copies outside the VPS and test a complete restore.
Does VoyraCloud automatically update Gitea?
No. New VPS resources receive the stable release approved for the image, while each owner controls later updates. Read the official upgrade notes, create a restorable backup, and test Git and authentication workflows after every change.
Is Residential IP VPS required for Gitea?
No. Cloud VPS is the normal general-purpose choice for a source-code service. Residential IP VPS is also technically supported when a broader workload specifically needs its network characteristics, but residential identity does not improve normal Git hosting by itself.
Conclusion
Self-hosting Gitea on a VPS gives developers and small teams control over repositories, accounts, collaboration data, network access, updates, and recovery. The VoyraCloud application image shortens the initial deployment by delivering a fixed stable Gitea environment with a locked installation page, private first-administrator setup, HTTPS and SSH Git access, and persistent local data.
That starting point still needs an owner. Add trusted HTTPS, use individual accounts and scoped credentials, keep registration aligned with your access policy, monitor capacity, pin updates, and maintain tested off-server backups before treating the service as critical infrastructure.
For the domain and reverse-proxy layer in front of the service, see the guide to Nginx Proxy Manager on a VPS.
Use the VoyraCloud application image for Gitea to begin from a preinstalled VPS environment while keeping your source-code service under your control.