# Common Use Cases for the Gitea Web Command: Server Management Guide

> Discover common use cases for the Gitea web command. Learn how it manages installation, server setup, reverse proxies, and graceful shutdowns in this essential guide.

- Repository: [Gitea/gitea](https://github.com/go-gitea/gitea)
- Tags: how-to-guide
- Published: 2026-03-07

---

**The `gitea web` command starts the Gitea HTTP(S) server, handles first-time installation, enables profiling, supports reverse proxy configurations, and manages graceful shutdowns via the `runWeb` function in [`cmd/web.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web.go).**

The `gitea web` sub-command serves as the primary entry point for running the Gitea self-hosted Git service. As implemented in the `go-gitea/gitea` repository, this command initializes the web server, applies configuration settings from `modules/setting`, and orchestrates multiple deployment scenarios ranging from local development to production clusters.

## Starting a Fresh Gitea Instance

When launching a new server, the `gitea web` command initializes the **graceful-shutdown manager**, loads HTML templates, and creates a PID file if the `--pid` flag is supplied. The **`runWeb`** function in **[`cmd/web.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web.go)** (lines 50-87) orchestrates this startup sequence, launching HTTP or HTTPS listeners based on the active configuration.

## Running the First-Time Installer

If **`setting.InstallLock`** equals `false`, indicating an uninitialized database, the command automatically enters installation mode. The **`serveInstall`** function in **[`cmd/web.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web.go)** (lines 74-78) serves the web-based setup UI on a temporary port and blocks execution until the administrator completes the configuration wizard.

## Serving Behind a Reverse Proxy

For production deployments behind nginx or Apache, the command respects **`setting.Protocol`**, **`setting.HTTPAddr`**, **`setting.HTTPPort`**, and **`setting.AppSubURL`**. The listener setup logic in **[`cmd/web.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web.go)** (lines 21-33) binds to custom addresses, Unix sockets, or specific ports, logging the final listener URL for diagnostic purposes.

## Enabling Runtime Profiling

When **`setting.EnablePprof`** is set to `true`, the command starts an auxiliary pprof server on `localhost:6060`. The **`servePprof`** function in **[`cmd/web.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web.go)** (lines 34-48) exposes Go runtime profiling endpoints at `/debug/pprof/*` to help diagnose memory leaks and performance bottlenecks.

## Automatic HTTPS with Let's Encrypt

For zero-configuration TLS, setting **`setting.EnableAcme`** triggers the ACME helper via **`runACME`** in **[`cmd/web_acme.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web_acme.go)**. This function automatically obtains and renews certificates from Let's Encrypt before starting the HTTPS listener, eliminating manual certificate management.

## Serving HTTPS with Custom Certificates

When deploying with existing SSL certificates, the command loads PEM files specified via configuration flags. The TLS loader in **[`cmd/web_https.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web_https.go)** (lines 31-68) builds a custom TLS configuration with secure cipher suites and launches the HTTPS server through **`runHTTPS`** or **`runHTTPSWithTLSConfig`**.

## FastCGI Deployment

For shared hosting environments or legacy integrations, setting the protocol to FastCGI invokes **`runFCGI`** in **[`cmd/web_graceful.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web_graceful.go)** (lines 32-49). This creates an FCGI server that forwards requests to Gitea's router while maintaining compatibility with external process managers.

## Graceful Shutdown and PID Management

The command registers system signal handlers through the **`modules/graceful`** package and writes process IDs via **`createPIDFile`**. This implementation in **[`cmd/web.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web.go)** (lines 65-70) ensures clean termination of active connections when receiving SIGTERM, which is critical for `systemctl stop gitea` operations.

## Essential Command-Line Examples

Practical invocations for common scenarios:

```bash

# Start Gitea with default HTTP on port 3000

gitea web

# Start Gitea on a custom port (e.g., 8080)

gitea web --port 8080

# Run Gitea behind a reverse proxy, using a Unix socket

gitea web --protocol unix --socket /var/run/gitea.sock

# Write the process ID to a custom file (useful for init scripts)

gitea web --pid /var/run/gitea.pid

# Enable verbose logging while the server is booting

gitea web --verbose

```

## Key Source Files Behind the Command

The `gitea web` implementation spans several specialized files:

- **[`cmd/web.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web.go)**: Core orchestration including flag definitions, PID handling (`createPIDFile`), installer flow (`serveInstall`), pprof initialization, and the main `runWeb` function.
- **[`cmd/web_acme.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web_acme.go)**: ACME/Let's Encrypt integration via `runACME` for automatic certificate acquisition and renewal.
- **[`cmd/web_https.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web_https.go)**: TLS configuration helpers, default cipher selection, and `runHTTPS`/`runHTTPSWithTLSConfig` implementations.
- **[`cmd/web_graceful.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web_graceful.go)**: Low-level HTTP/FCGI listeners (`runFCGI`) and graceful shutdown plumbing.
- **`modules/graceful`**: Manages process lifecycles, signal handling, and clean-up of listeners.
- **`modules/setting`**: Stores server-wide configuration including ports, URLs, TLS options, and protocol settings consumed by the web command.

## Summary

- The `gitea web` command serves as the primary entry point for starting the Gitea HTTP(S) server in both development and production environments.
- It automatically detects uninitialized instances via `setting.InstallLock` and launches the browser-based installer when necessary.
- The command supports multiple deployment modes including reverse proxy setups, FastCGI, custom TLS certificates, and automatic Let's Encrypt integration via [`cmd/web_acme.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web_acme.go).
- Runtime profiling is available through `setting.EnablePprof`, which exposes pprof endpoints on `localhost:6060` through `servePprof`.
- Graceful shutdown capabilities in [`cmd/web.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web.go) ensure clean process termination for systemd integration and production deployments.

## Frequently Asked Questions

### What does the gitea web command do?

The `gitea web` command initializes and runs the Gitea web server, handling HTTP/HTTPS listeners, configuration loading from `modules/setting`, and optional features like pprof profiling and ACME certificate management. It serves as the main entry point defined in [`cmd/web.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web.go) through the `runWeb` function.

### How do I run Gitea on a custom port?

Pass the `--port` flag followed by the desired port number, such as `gitea web --port 8080`. The command reads this flag in [`cmd/web.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web.go) and overrides the default `setting.HTTPPort` value during listener initialization.

### Does gitea web support automatic HTTPS?

Yes, when `setting.EnableAcme` is configured, the command executes `runACME` from [`cmd/web_acme.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web_acme.go) to automatically obtain and renew TLS certificates from Let's Encrypt before starting the secure listener.

### How does Gitea handle graceful shutdown?

The `gitea web` command integrates with `modules/graceful` to register signal handlers that trigger clean shutdown sequences. When the process receives a termination signal, it stops accepting new connections, finishes processing active requests, and removes the PID file created via `createPIDFile` in [`cmd/web.go`](https://github.com/go-gitea/gitea/blob/main/cmd/web.go).