> ## 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.

# Installation

> Install Gitea on your platform with Docker, binaries, package managers, or from source

## Choose Your Installation Method

Gitea offers multiple installation methods to suit your needs. Choose the one that works best for your environment.

<CardGroup cols={2}>
  <Card title="Docker" icon="docker">
    **Recommended** - Fastest way to get started with full isolation
  </Card>

  <Card title="Binary" icon="file-binary">
    Single executable file - no dependencies required
  </Card>

  <Card title="Package Manager" icon="box">
    Install via your system's package manager
  </Card>

  <Card title="From Source" icon="code">
    Build from source for development or customization
  </Card>
</CardGroup>

## Docker Installation

<Note>
  Docker is the recommended installation method for most users. It provides isolation, easy updates, and consistent behavior across platforms.
</Note>

### Using Docker

The simplest way to run Gitea is with Docker:

<Steps>
  <Step title="Create directories for persistent data">
    ```bash theme={null}
    mkdir -p /var/lib/gitea
    ```
  </Step>

  <Step title="Run Gitea container">
    ```bash theme={null}
    docker run -d \
      --name=gitea \
      -p 3000:3000 \
      -p 222:22 \
      -v /var/lib/gitea:/data \
      -e USER_UID=1000 \
      -e USER_GID=1000 \
      gitea/gitea:latest
    ```

    <Info>
      * Port 3000: Web interface (HTTP)
      * Port 222: SSH access (mapped to container's port 22)
      * Volume `/data`: Persistent storage for repositories and database
    </Info>
  </Step>

  <Step title="Access Gitea">
    Open your browser and navigate to `http://localhost:3000`

    You'll see the initial configuration page where you can set up your instance.
  </Step>
</Steps>

### Using Docker Compose

For production deployments, use Docker Compose with a PostgreSQL database:

<CodeGroup>
  ```yaml docker-compose.yml theme={null}
  version: "3"

  networks:
    gitea:
      external: false

  services:
    server:
      image: gitea/gitea:latest
      container_name: gitea
      environment:
        - USER_UID=1000
        - USER_GID=1000
        - GITEA__database__DB_TYPE=postgres
        - GITEA__database__HOST=db:5432
        - GITEA__database__NAME=gitea
        - GITEA__database__USER=gitea
        - GITEA__database__PASSWD=gitea
      restart: always
      networks:
        - gitea
      volumes:
        - ./gitea:/data
        - /etc/timezone:/etc/timezone:ro
        - /etc/localtime:/etc/localtime:ro
      ports:
        - "3000:3000"
        - "222:22"
      depends_on:
        - db

    db:
      image: postgres:14
      restart: always
      environment:
        - POSTGRES_USER=gitea
        - POSTGRES_PASSWORD=gitea
        - POSTGRES_DB=gitea
      networks:
        - gitea
      volumes:
        - ./postgres:/var/lib/postgresql/data
  ```

  ```bash Start with Docker Compose theme={null}
  docker-compose up -d
  ```
</CodeGroup>

<Warning>
  Make sure to change the default passwords in production!
</Warning>

### Docker Rootless

For enhanced security, run Gitea as a non-root user:

```bash theme={null}
docker run -d \
  --name=gitea \
  -p 3000:3000 \
  -p 222:2222 \
  -v /var/lib/gitea:/var/lib/gitea \
  -e USER_UID=1000 \
  -e USER_GID=1000 \
  gitea/gitea:latest-rootless
```

## Binary Installation

Install Gitea as a standalone binary - perfect for environments without Docker.

<Steps>
  <Step title="Download the binary">
    Download the latest release for your platform from [dl.gitea.com](https://dl.gitea.com/gitea/):

    <Tabs>
      <Tab title="Linux (amd64)">
        ```bash theme={null}
        wget -O gitea https://dl.gitea.com/gitea/1.22/gitea-1.22-linux-amd64
        chmod +x gitea
        ```
      </Tab>

      <Tab title="Linux (arm64)">
        ```bash theme={null}
        wget -O gitea https://dl.gitea.com/gitea/1.22/gitea-1.22-linux-arm64
        chmod +x gitea
        ```
      </Tab>

      <Tab title="macOS">
        ```bash theme={null}
        wget -O gitea https://dl.gitea.com/gitea/1.22/gitea-1.22-darwin-amd64
        chmod +x gitea
        ```
      </Tab>

      <Tab title="Windows">
        Download `gitea-1.22-windows-amd64.exe` from [dl.gitea.com](https://dl.gitea.com/gitea/1.22/)
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify the binary (optional but recommended)">
    ```bash theme={null}
    # Download the checksum
    wget https://dl.gitea.com/gitea/1.22/gitea-1.22-linux-amd64.sha256

    # Verify
    sha256sum -c gitea-1.22-linux-amd64.sha256
    ```
  </Step>

  <Step title="Run Gitea">
    ```bash theme={null}
    ./gitea web
    ```

    Gitea will start on port 3000. Open `http://localhost:3000` to complete the setup.
  </Step>
</Steps>

### Setting up as a Service

For production use, run Gitea as a system service:

<Tabs>
  <Tab title="systemd (Linux)">
    <Steps>
      <Step title="Create a git user">
        ```bash theme={null}
        sudo adduser \
          --system \
          --shell /bin/bash \
          --gecos 'Git Version Control' \
          --group \
          --disabled-password \
          --home /home/git \
          git
        ```
      </Step>

      <Step title="Create required directories">
        ```bash theme={null}
        sudo mkdir -p /var/lib/gitea/{custom,data,log}
        sudo chown -R git:git /var/lib/gitea/
        sudo chmod -R 750 /var/lib/gitea/

        sudo mkdir /etc/gitea
        sudo chown root:git /etc/gitea
        sudo chmod 770 /etc/gitea
        ```
      </Step>

      <Step title="Copy binary to system location">
        ```bash theme={null}
        sudo cp gitea /usr/local/bin/gitea
        sudo chmod +x /usr/local/bin/gitea
        ```
      </Step>

      <Step title="Create systemd service file">
        Create `/etc/systemd/system/gitea.service` with the following content:

        ```ini theme={null}
        [Unit]
        Description=Gitea (Git with a cup of tea)
        After=network.target

        [Service]
        RestartSec=2s
        Type=simple
        User=git
        Group=git
        WorkingDirectory=/var/lib/gitea/
        ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
        Restart=always
        Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

        [Install]
        WantedBy=multi-user.target
        ```
      </Step>

      <Step title="Enable and start the service">
        ```bash theme={null}
        sudo systemctl daemon-reload
        sudo systemctl enable gitea
        sudo systemctl start gitea

        # Check status
        sudo systemctl status gitea
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows Service">
    Use NSSM (Non-Sucking Service Manager) to run Gitea as a Windows service:

    ```powershell theme={null}
    # Download NSSM from https://nssm.cc/download

    # Install Gitea as a service
    nssm install Gitea "C:\gitea\gitea.exe" web

    # Start the service
    nssm start Gitea
    ```
  </Tab>
</Tabs>

## Package Manager Installation

<Tabs>
  <Tab title="Homebrew (macOS/Linux)">
    ```bash theme={null}
    brew install gitea

    # Start Gitea
    gitea web
    ```
  </Tab>

  <Tab title="Snap (Linux)">
    ```bash theme={null}
    snap install gitea
    ```
  </Tab>

  <Tab title="Arch Linux (AUR)">
    ```bash theme={null}
    yay -S gitea
    # or
    paru -S gitea

    # Start and enable service
    sudo systemctl enable --now gitea
    ```
  </Tab>

  <Tab title="Debian/Ubuntu">
    <Info>
      Gitea is not in official Debian/Ubuntu repositories. Use Docker, binary, or build from source.
    </Info>
  </Tab>
</Tabs>

## Building from Source

For developers or custom builds with specific features:

<Steps>
  <Step title="Prerequisites">
    * **Go 1.26 or higher** - Check with `go version`
    * **Node.js LTS** (for frontend) - Check with `node --version`
    * **pnpm** - Install with `npm install -g pnpm`
    * **Git** - Check with `git --version`
    * **Build tools** - gcc/build-essential
  </Step>

  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/go-gitea/gitea.git
    cd gitea
    ```
  </Step>

  <Step title="Build Gitea">
    <Tabs>
      <Tab title="Standard Build">
        ```bash theme={null}
        TAGS="bindata" make build
        ```
      </Tab>

      <Tab title="With SQLite Support">
        ```bash theme={null}
        TAGS="bindata sqlite sqlite_unlock_notify" make build
        ```
      </Tab>

      <Tab title="Backend Only">
        ```bash theme={null}
        TAGS="bindata" make backend
        ```
      </Tab>
    </Tabs>

    <Note>
      Building takes a few minutes. The `bindata` tag embeds static assets into the binary.
    </Note>
  </Step>

  <Step title="Run Gitea">
    ```bash theme={null}
    ./gitea web
    ```

    The binary will be created in the project root directory.
  </Step>
</Steps>

<Info>
  For more detailed build instructions, see the [CONTRIBUTING.md](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md) file in the repository.
</Info>

## Database Setup

Gitea supports multiple database backends:

<Tabs>
  <Tab title="SQLite (Default)">
    No setup required! Gitea uses SQLite by default.

    Perfect for:

    * Small installations (\< 100 users)
    * Personal use
    * Testing and development

    <Note>
      SQLite is embedded and requires no separate database server.
    </Note>
  </Tab>

  <Tab title="PostgreSQL (Recommended)">
    ```bash theme={null}
    # Install PostgreSQL
    sudo apt-get install postgresql

    # Create database and user
    sudo -u postgres psql
    ```

    ```sql theme={null}
    CREATE USER gitea WITH PASSWORD 'gitea';
    CREATE DATABASE gitea OWNER gitea;
    \q
    ```

    During Gitea setup, enter:

    * **Database Type**: PostgreSQL
    * **Host**: localhost:5432
    * **Username**: gitea
    * **Password**: gitea
    * **Database Name**: gitea
  </Tab>

  <Tab title="MySQL/MariaDB">
    ```bash theme={null}
    # Install MySQL/MariaDB
    sudo apt-get install mysql-server

    # Create database and user
    sudo mysql
    ```

    ```sql theme={null}
    CREATE DATABASE gitea CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci';
    CREATE USER 'gitea'@'localhost' IDENTIFIED BY 'gitea';
    GRANT ALL PRIVILEGES ON gitea.* TO 'gitea'@'localhost';
    FLUSH PRIVILEGES;
    EXIT;
    ```
  </Tab>
</Tabs>

## Initial Configuration

After starting Gitea for the first time:

<Steps>
  <Step title="Access the installer">
    Navigate to `http://localhost:3000` in your browser
  </Step>

  <Step title="Configure database">
    Choose your database type and enter connection details
  </Step>

  <Step title="Configure server settings">
    * **Server Domain**: Your domain or IP address
    * **SSH Port**: 22 (or custom port)
    * **HTTP Port**: 3000 (or custom port)
    * **Base URL**: Full URL to access Gitea
  </Step>

  <Step title="Create admin account">
    Set up the administrator account for your instance
  </Step>

  <Step title="Complete installation">
    Click "Install Gitea" to finalize the setup
  </Step>
</Steps>

<Info>
  After installation, the configuration is saved to `custom/conf/app.ini`. You can manually edit this file for advanced configuration.
</Info>

## Firewall Configuration

If you're using a firewall, open the necessary ports:

```bash theme={null}
# For UFW (Ubuntu/Debian)
sudo ufw allow 3000/tcp  # HTTP
sudo ufw allow 222/tcp   # SSH (if using custom port)

# For firewalld (CentOS/RHEL)
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=222/tcp
sudo firewall-cmd --reload
```

## Upgrading Gitea

<Tabs>
  <Tab title="Docker">
    ```bash theme={null}
    # Stop the container
    docker stop gitea

    # Remove the old container
    docker rm gitea

    # Pull the latest image
    docker pull gitea/gitea:latest

    # Start with the same command you used initially
    docker run -d ...
    ```
  </Tab>

  <Tab title="Binary">
    ```bash theme={null}
    # Stop Gitea
    sudo systemctl stop gitea

    # Backup the old binary
    sudo cp /usr/local/bin/gitea /usr/local/bin/gitea.backup

    # Download and replace with new binary
    sudo wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea/1.22/gitea-1.22-linux-amd64
    sudo chmod +x /usr/local/bin/gitea

    # Start Gitea
    sudo systemctl start gitea
    ```
  </Tab>
</Tabs>

<Warning>
  Always backup your data before upgrading! Backup at minimum:

  * Database (if using external DB)
  * `custom/conf/app.ini` configuration file
  * Repository data directory
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Gitea won't start">
    Check the logs:

    * Docker: `docker logs gitea`
    * Systemd: `sudo journalctl -u gitea -n 50`
    * Binary: Check `log/gitea.log` in your work directory

    Common issues:

    * Port already in use
    * Permission issues with data directory
    * Database connection problems
  </Accordion>

  <Accordion title="Can't access via browser">
    * Check if Gitea is running: `sudo systemctl status gitea` or `docker ps`
    * Verify firewall settings
    * Check that you're using the correct IP/domain and port
    * Look for errors in logs
  </Accordion>

  <Accordion title="Database connection failed">
    * Verify database is running
    * Check connection credentials in `app.ini`
    * Ensure database user has proper permissions
    * For PostgreSQL, check `pg_hba.conf` for connection rules
  </Accordion>

  <Accordion title="SSH not working">
    * Ensure SSH port is open in firewall
    * Check SSH server is running
    * Verify SSH keys are properly configured
    * Check `SSH_PORT` in `app.ini`
  </Accordion>
</AccordionGroup>

## Next Steps

Gitea is now installed! Continue with:

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/quickstart">
    Follow our 5-minute quick start to create your first repository
  </Card>

  <Card title="Configuration" icon="gear" href="/admin/configuration">
    Learn about advanced configuration options
  </Card>
</CardGroup>