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

# Building from Source

> Build Gitea from source code for development and customization

## Prerequisites

Before building Gitea, ensure you have the following installed:

### Required

* **Go**: Version 1.26.1 or later (as specified in `go.mod`)
* **Node.js**: Version 22.6.0 or later
* **pnpm**: Version 10.0.0 or later
* **Git**: For cloning the repository
* **Make**: Build automation

### Optional

* **Docker**: For building Docker images
* **SQLite3**: If building with SQLite support

## Installation

<Tabs>
  <Tab title="Go">
    Install Go from [go.dev/dl](https://go.dev/dl/)

    ```bash theme={null}
    # Verify installation
    go version
    # Should output: go version go1.26.1 or later
    ```
  </Tab>

  <Tab title="Node.js & pnpm">
    Install Node.js from [nodejs.org](https://nodejs.org/)

    ```bash theme={null}
    # Verify Node.js installation
    node --version
    # Should output: v22.6.0 or later

    # Install pnpm globally
    npm install -g pnpm

    # Verify pnpm installation
    pnpm --version
    # Should output: 10.0.0 or later
    ```
  </Tab>
</Tabs>

## Clone the Repository

```bash theme={null}
# Clone Gitea repository
git clone https://github.com/go-gitea/gitea.git
cd gitea
```

## Building Gitea

### Basic Build

Build Gitea with embedded assets:

```bash theme={null}
TAGS="bindata" make build
```

This creates a `gitea` binary in the root directory.

### Build with SQLite Support

To include SQLite database support:

```bash theme={null}
TAGS="bindata sqlite sqlite_unlock_notify" make build
```

<Note>
  SQLite support requires CGO to be enabled and SQLite3 development headers installed.
</Note>

### Build Targets

The build process is split into two main targets:

<Tabs>
  <Tab title="Backend">
    Build only the Go backend:

    ```bash theme={null}
    make backend
    ```

    **Requirements**: Go 1.26.1+
  </Tab>

  <Tab title="Frontend">
    Build only the frontend assets:

    ```bash theme={null}
    make frontend
    ```

    **Requirements**: Node.js 22.6.0+ and pnpm 10.0.0+
  </Tab>
</Tabs>

### Build Tags

Common build tags:

| Tag                    | Description                        |
| ---------------------- | ---------------------------------- |
| `bindata`              | Embed static assets into binary    |
| `sqlite`               | Enable SQLite database support     |
| `sqlite_unlock_notify` | Enable SQLite unlock notifications |
| `pam`                  | Enable PAM authentication          |
| `gogit`                | Use pure Go git implementation     |

**Example with multiple tags:**

```bash theme={null}
TAGS="bindata sqlite sqlite_unlock_notify pam" make build
```

## Development Build

For development with live reloading:

```bash theme={null}
# Install dependencies
make deps-frontend
make deps-backend

# Run in development mode
make watch-frontend &  # Watch and rebuild frontend
make watch-backend     # Watch and rebuild backend
```

Or use [Air](https://github.com/cosmtrek/air) for automatic reloading:

```bash theme={null}
# Install air
go install github.com/cosmtrek/air@latest

# Run with air
air -c .air.toml
```

## Building for Production

### Optimized Build

```bash theme={null}
# Clean previous builds
make clean

# Build optimized binary
TAGS="bindata" make build

# Strip debug symbols for smaller binary
strip gitea
```

### Cross-Compilation

Build for different platforms:

<CodeGroup>
  ```bash Linux ARM64 theme={null}
  GOOS=linux GOARCH=arm64 TAGS="bindata" make build
  ```

  ```bash macOS theme={null}
  GOOS=darwin GOARCH=amd64 TAGS="bindata" make build
  ```

  ```bash Windows theme={null}
  GOOS=windows GOARCH=amd64 TAGS="bindata" make build
  ```
</CodeGroup>

## Building Docker Images

### Standard Docker Image

```bash theme={null}
# Build Docker image
make docker

# Or use docker-compose
docker build -t gitea:latest .
```

### Rootless Docker Image

```bash theme={null}
docker build -f Dockerfile.rootless -t gitea:rootless .
```

## Makefile Targets

Common make targets:

```bash theme={null}
# Show all available targets
make help

# Build targets
make build          # Build complete Gitea binary
make backend        # Build backend only
make frontend       # Build frontend only

# Development
make watch-frontend # Watch and rebuild frontend
make watch-backend  # Watch and rebuild backend

# Testing
make test          # Run all tests
make test-sqlite   # Run tests with SQLite

# Code quality
make fmt           # Format Go code
make lint-go       # Lint Go code
make lint-js       # Lint JavaScript/TypeScript
make tidy          # Tidy go.mod

# Cleanup
make clean         # Remove build artifacts
```

## Configuration

### Development Configuration

Create a custom configuration for development:

```bash theme={null}
# Create custom config directory
mkdir -p custom/conf

# Create app.ini
cat > custom/conf/app.ini << EOF
APP_NAME = Gitea: Git with a cup of tea (Dev)
RUN_MODE = dev

[server]
HTTP_PORT = 3000
ROOT_URL = http://localhost:3000/

[database]
DB_TYPE = sqlite3
PATH = data/gitea.db

[log]
ROOT_PATH = log
MODE = console
LEVEL = Debug
EOF
```

### Running the Development Build

```bash theme={null}
# Run Gitea
./gitea web

# Or with custom config
./gitea web -c custom/conf/app.ini
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Build fails with 'cannot find package'">
    Run `make deps-backend` to download Go dependencies:

    ```bash theme={null}
    make deps-backend
    go mod download
    ```
  </Accordion>

  <Accordion title="Frontend build fails">
    Ensure you're using the correct Node.js and pnpm versions:

    ```bash theme={null}
    node --version  # Should be >= 22.6.0
    pnpm --version  # Should be >= 10.0.0

    # Clean and reinstall
    rm -rf node_modules
    pnpm install
    ```
  </Accordion>

  <Accordion title="SQLite build fails">
    Install SQLite3 development headers:

    <CodeGroup>
      ```bash Ubuntu/Debian theme={null}
      sudo apt-get install libsqlite3-dev
      ```

      ```bash macOS theme={null}
      brew install sqlite3
      ```

      ```bash Fedora theme={null}
      sudo dnf install sqlite-devel
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Build is very slow">
    * Use `make backend` instead of full build during development
    * Enable build cache: `GOCACHE=$(go env GOCACHE)`
    * Use faster linker: `go build -ldflags='-s -w'`
  </Accordion>
</AccordionGroup>

## See Also

<CardGroup cols={2}>
  <Card title="Contributing" href="/development/contributing">
    Learn how to contribute to Gitea
  </Card>

  <Card title="Testing" href="/development/testing">
    Run tests and write new tests
  </Card>

  <Card title="Architecture" href="/development/architecture">
    Understand Gitea's codebase structure
  </Card>

  <Card title="Installation" href="/installation">
    Install pre-built Gitea binaries
  </Card>
</CardGroup>