> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure Gitea using app.ini and environment variables

## Overview

Gitea is configured through the `app.ini` file located in `custom/conf/app.ini`. You can also use environment variables to override configuration values.

## Configuration File Location

The configuration file path is determined by the following hierarchy:

1. `--config` flag passed to the binary
2. Built-in value set at build time
3. Default: `{CustomPath}/conf/app.ini`

To find your configuration location, run:

```bash theme={null}
gitea help
```

## General Settings

### Application Settings

<ParamField path="APP_NAME" type="string" default="Gitea: Git with a cup of tea">
  Application name shown in page titles
</ParamField>

<ParamField path="RUN_USER" type="string" default="git">
  Operating system user that runs Gitea. Automatically detected if not set.
</ParamField>

<ParamField path="RUN_MODE" type="string" default="prod">
  Application run mode: `dev` or `prod`. Dev mode provides easier debugging.
</ParamField>

<ParamField path="WORK_PATH" type="string">
  Working directory for Gitea. Defaults to the directory containing the binary.
</ParamField>

## Server Configuration

All server settings are configured in the `[server]` section.

### Protocol and Domain

<ParamField path="PROTOCOL" type="string" default="http">
  Protocol the server listens on: `http`, `https`, `http+unix`, `fcgi`, or `fcgi+unix`
</ParamField>

<ParamField path="DOMAIN" type="string" default="localhost">
  Domain name of the server
</ParamField>

<ParamField path="ROOT_URL" type="string">
  Public URL of the Gitea instance. Defaults to `{PROTOCOL}://{DOMAIN}:{HTTP_PORT}/`
</ParamField>

<ParamField path="HTTP_ADDR" type="string" default="0.0.0.0">
  HTTP listen address. Can be an IPv4/IPv6 address or Unix socket path.
</ParamField>

<ParamField path="HTTP_PORT" type="string" default="3000">
  HTTP listen port
</ParamField>

### SSH Configuration

<ParamField path="DISABLE_SSH" type="boolean" default="false">
  Disable SSH feature when not available
</ParamField>

<ParamField path="START_SSH_SERVER" type="boolean" default="false">
  Use built-in SSH server instead of system SSH
</ParamField>

<ParamField path="SSH_DOMAIN" type="string">
  Domain name exposed in clone URLs. Defaults to DOMAIN or ROOT\_URL domain.
</ParamField>

<ParamField path="SSH_PORT" type="number" default="22">
  SSH port exposed in clone URLs
</ParamField>

<ParamField path="SSH_LISTEN_PORT" type="number">
  Port the built-in SSH server listens on. Defaults to SSH\_PORT.
</ParamField>

### TLS Configuration

<ParamField path="ENABLE_ACME" type="boolean" default="false">
  Enable automatic TLS certificate generation via ACME (Let's Encrypt)
</ParamField>

<ParamField path="CERT_FILE" type="string" default="https/cert.pem">
  Path to TLS certificate file (manual TLS only)
</ParamField>

<ParamField path="KEY_FILE" type="string" default="https/key.pem">
  Path to TLS key file (manual TLS only)
</ParamField>

## Storage Configuration

<ParamField path="APP_DATA_PATH" type="string" default="data">
  Default path for storing application data
</ParamField>

<ParamField path="STATIC_ROOT_PATH" type="string">
  Root directory containing templates and static files
</ParamField>

### LFS Configuration

<ParamField path="LFS_START_SERVER" type="boolean" default="false">
  Enable Git LFS support
</ParamField>

<ParamField path="LFS_JWT_SECRET" type="string">
  LFS authentication secret. Change this to a random value.
</ParamField>

<ParamField path="LFS_HTTP_AUTH_EXPIRY" type="duration" default="24h">
  LFS authentication validity period
</ParamField>

<ParamField path="LFS_MAX_FILE_SIZE" type="number" default="0">
  Maximum allowed LFS file size in bytes (0 = no limit)
</ParamField>

## Security Configuration

All security settings are in the `[security]` section.

<ParamField path="INSTALL_LOCK" type="boolean" default="false">
  Disable the web installer. Set to true after installation.
</ParamField>

<ParamField path="SECRET_KEY" type="string">
  Global secret key for encryption. CRITICAL: Do not lose this key.
</ParamField>

<ParamField path="INTERNAL_TOKEN" type="string">
  Secret for internal API communication between Gitea components
</ParamField>

<ParamField path="PASSWORD_HASH_ALGO" type="string" default="pbkdf2">
  Password hashing algorithm: `pbkdf2`, `argon2`, `scrypt`, `bcrypt`
</ParamField>

## Admin Settings

Configure admin-specific behavior in the `[admin]` section.

<ParamField path="DISABLE_REGULAR_ORG_CREATION" type="boolean" default="false">
  Prevent non-admin users from creating organizations
</ParamField>

<ParamField path="DEFAULT_EMAIL_NOTIFICATIONS" type="string" default="enabled">
  Default email notification preference for new users
</ParamField>

<ParamField path="USER_DISABLED_FEATURES" type="string">
  Comma-separated list of disabled features for all users:

  * `deletion` - Account deletion
  * `manage_ssh_keys` - SSH key management
  * `manage_gpg_keys` - GPG key management
  * `manage_mfa` - Multi-factor authentication
  * `manage_credentials` - Access token management
  * `change_username` - Username changes
  * `change_full_name` - Full name changes
</ParamField>

<ParamField path="EXTERNAL_USER_DISABLE_FEATURES" type="string">
  Additional disabled features for external authentication users (LDAP, OAuth2, etc.)
</ParamField>

## Environment Variables

You can override any configuration value using environment variables with the format:

```bash theme={null}
GITEA__SECTION__KEY=value
```

### Examples

```bash theme={null}
# Override database type
export GITEA__database__DB_TYPE=postgres

# Override server port
export GITEA__server__HTTP_PORT=8080

# Override admin settings
export GITEA__admin__DISABLE_REGULAR_ORG_CREATION=true
```

## Viewing Configuration

To view the current configuration, use:

```bash theme={null}
gitea manager show-config
```

This displays the effective configuration, including defaults and overrides.

## Configuration Validation

After modifying `app.ini`, validate your configuration:

```bash theme={null}
gitea doctor check --run config
```

## Best Practices

<Steps>
  <Step title="Use Version Control">
    Keep your `app.ini` in version control (excluding secrets)
  </Step>

  <Step title="Externalize Secrets">
    Use `*_URI` options to store secrets in external files:

    ```ini theme={null}
    SECRET_KEY_URI = file:/etc/gitea/secret_key
    LFS_JWT_SECRET_URI = file:/etc/gitea/lfs_jwt_secret
    ```
  </Step>

  <Step title="Minimal Configuration">
    Only set values that differ from defaults. Smaller config files are easier to maintain.
  </Step>

  <Step title="Test Changes">
    Always test configuration changes in a non-production environment first
  </Step>
</Steps>

## Related Resources

* [Database Configuration](/admin/database)
* [Authentication Configuration](/admin/authentication)
* [Backup and Restore](/admin/backup-restore)
* [Command-Line Tools](/admin/command-line)