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

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.

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 (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 (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 (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 (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. 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 (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 (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 (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:

# 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: Core orchestration including flag definitions, PID handling (createPIDFile), installer flow (serveInstall), pprof initialization, and the main runWeb function.
• cmd/web_acme.go: ACME/Let's Encrypt integration via runACME for automatic certificate acquisition and renewal.
• cmd/web_https.go: TLS configuration helpers, default cipher selection, and runHTTPS/runHTTPSWithTLSConfig implementations.
• 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.
• Runtime profiling is available through setting.EnablePprof, which exposes pprof endpoints on localhost:6060 through servePprof.
• Graceful shutdown capabilities in 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}