Gitea

Gitea provides the Development use case. The dev workload with Gitea runs a private Git server in a rootless container with SQLite on one selected node. Public registration is disabled and new repositories are forced private. It does not expose SSH, install a CI runner, or enable Actions; workflows for additional users and API tokens stay native Gitea operations. The use-case catalog lists the components the published release declares.

What it is

Gitea is a private place to keep your code, similar to a small self-run version of a code hosting website. You push projects to it with ordinary Git tools and keep them private. A StackKit includes it so your repositories do not have to live with an outside provider.

Which kits and use cases include it

Gitea is the default application of the Developer Platform part of the Dev use case. The example below uses basement-kit on standalone Compose. Per the evidence state on the Development page, it is selectable but not yet lifecycle-verified.

How to open it

Open the route you configure for the workload; the example uses https://dev.lab.home. The hostname must resolve to your host from every client, as described below.

Select the dev workload explicitly

From an empty owner workspace, select Gitea and establish its local owner custody:

stackkit init basement-kit --platform standalone-compose \
  --use-case dev --use-case-alternative dev=gitea \
  --use-case-alternative basement-core=standalone \
  --module-compute-profile stackkits-basement-core-runtime=standard \
  --module-compute-profile stackkits-gitea-runtime=standard \
  --owner-source local --owner-email owner@example.com --non-interactive

Before generating, merge the following fields into the existing capabilities, data and routes sections of your StackSpec. Preserve their other entries. This fragment uses the initial home site and home-private access policy; adapt those references, the home domain and host storage roots to your actual host.

capabilities:
  enable: [internal-pki]
data:
  bindings:
    dev:
      classes: [personal]
      primarySiteRef: home
routes:
  dev:
    serviceRef: dev
    moduleRef: stackkits-gitea-runtime
    exposure: local
    protocol: https
    port: 443
    targetPort: 3000
    host: dev.lab.home
    path: /
    accessPolicyRef: home-private

Gitea requires this explicit HTTPS route and data binding for usable native clone URLs. Validate and generate the result:

stackkit validate
stackkit generate --local-node main --local-site home

Then follow the normal delivery lifecycle: validate, inspect the plan, and apply and verify as documented in Review, apply, and verify. Observed host inventory must satisfy the selected module profiles; the example configuration is not hardware evidence.

Provide the name and trust the route works

Native HTTPS Git needs two things your host must already satisfy:

The route’s hostname (the example uses dev.lab.home) must resolve to that host from every client you intend to clone.
Git clients must trust the host’s internal CA certificate. Without client trust, HTTPS cloning fails before authentication.

First startup migrates the SQLite database and creates administrator owner before serving traffic; owner email comes from your local owner identity, and the owner-password reference is held in existing local secret custody. Read the password in a private terminal:

stackkit secrets reveal --workload dev --slot owner-password

The command accepts only slots declared by the current validated StackSpec, writes the value to stdout — never to deployment logs — and neither creates nor resets a password. An existing unmatched administrator or an unowned user database fails delivery without replacing accounts or resetting passwords.

First use

Reveal the owner password with the command above in a private terminal.
Open the Gitea route and sign in as owner.
Create a private repository.
Copy its HTTPS clone URL and clone it from a real client, using your native Git credential storage.
Push a small test commit.

Sign in as owner, create a private repository, and use its HTTPS clone URL with your native Git credential storage. Git authenticates directly with Gitea: no browser forward-auth gate intercepts Git requests. Readiness that only reports the HTTP process and SQLite as reachable does not prove you have cloned, pushed, or recovered anything — test an actual push from an intended client.

Storage and recovery boundary

Allocation	Container path	Contents
`gitea/data`	`/var/lib/gitea`	SQLite database, repositories, LFS objects, application data
`gitea/config`	`/etc/gitea`	`app.ini` and persisted application keys/configuration

Both named volumes belong to the workload’s data and backup contract. Correct recovery quiesces the application’s single writer, captures both volumes, and activates them together with writes stopped — a live copy of the SQLite file alone is not that contract. Follow Back up and restore for the workspace lifecycle. Rootless and rootful Gitea use different layouts, so swapping the image is not a storage migration.

What to expect

Gitea is a single small server using SQLite on one selected node. Sign-in and repository pages are fast for a household. If the page loads but cloning fails, the usual cause is name resolution or certificate trust, not Gitea itself.

If something goes wrong

Cloning fails before asking for a password: the hostname does not resolve from that client, or the client does not trust the internal CA certificate.
You cannot remember the owner password: reveal it again with stackkit secrets reveal --workload dev --slot owner-password; the command neither creates nor resets a password.
Delivery fails on an existing administrator or user database: it does not replace accounts or reset passwords; resolve the conflict deliberately first.
Compare any address with the rollout output and see Troubleshooting.

Known limits

SSH is not exposed; native HTTPS is the documented Git access path.
Gitea Actions and CI runners are not installed; runner integration has no documented path yet.
Forced container recreation retains owner access, private repository metadata, and the application configuration, but complete Linux host provisioning, real LAN DNS/CA distribution, and a full backup/restore cycle are separate evidence tiers and not proven here.

Get started

Get help

Guides

Reference

What it is

Which kits and use cases include it

How to open it

Select the dev workload explicitly

Provide the name and trust the route works

First use

Storage and recovery boundary

What to expect

If something goes wrong

Known limits

​What it is

​Which kits and use cases include it

​How to open it

​Select the dev workload explicitly

​Provide the name and trust the route works

​Reveal the owner password and sign in

​First use

​Storage and recovery boundary

​What to expect

​If something goes wrong

​Known limits

What it is

Which kits and use cases include it

How to open it

Select the dev workload explicitly

Provide the name and trust the route works

Reveal the owner password and sign in

First use

Storage and recovery boundary

What to expect

If something goes wrong

Known limits