---
title: Building from Source
description: Compile Alita Robot from source code.
---

Build Alita Robot from source for development, customization, or when pre-built binaries are not available for your platform.

## Prerequisites

:::note
All tools below must be accessible from your `PATH`. After installing Go or golangci-lint, you may need to add `$(go env GOPATH)/bin` to your shell's `PATH`.
:::

| Tool | Minimum Version | Purpose |
|------|-----------------|---------|
| **Go** | 1.26+ | Compilation |
| **Git** | 2.0+ | Clone repository |
| **Make** | Any | Build automation |
| **golangci-lint** | v2.14.0+ (v2 required) | Code quality checks |

### Install Go

**macOS**

```bash
brew install go
```

**Ubuntu/Debian**

```bash
sudo snap install go --classic
```

**Manual Download**

Download from [https://go.dev/dl/](https://go.dev/dl/)

### Install golangci-lint

**macOS**

```bash
brew install golangci-lint
```

**Linux/macOS Script**

```bash
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin
```

**Go Install**

```bash
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.14.0
```

## Clone the Repository

```bash
git clone https://github.com/divkix/Alita_Robot.git
cd Alita_Robot
```

## Build Commands

### Development Build

Run the bot directly from source:

```bash
# Using Make
make run

# Or using Go directly
go run main.go
```

### Production Build

1. **Install GoReleaser**

    ```bash
    go install github.com/goreleaser/goreleaser/v2@latest
    ```

2. **Build release binaries**

    ```bash
    make build
    ```

    This runs `goreleaser release --snapshot --skip=publish`, which builds binaries and archives in `dist/` for all supported platforms and also builds the `linux/amd64` and `linux/arm64` Docker images, so Docker with buildx must be installed and running. For binaries only, use `goreleaser build --snapshot --clean` or the Manual Build below.

### Manual Build

Build for your current platform:

```bash
go build -o alita_robot .
```

:::tip[Smaller Binaries]
Build with optimizations to strip debug symbols and reduce binary size:
```bash
go build -ldflags="-s -w" -o alita_robot .
```
:::

Cross-compile for other platforms:

```bash
# Linux amd64
GOOS=linux GOARCH=amd64 go build -o alita_robot_linux_amd64 .

# macOS arm64
GOOS=darwin GOARCH=arm64 go build -o alita_robot_darwin_arm64 .

# Windows amd64
GOOS=windows GOARCH=amd64 go build -o alita_robot_windows_amd64.exe .
```

## Makefile Targets

| Target | Command | Description |
|--------|---------|-------------|
| `run` | `make run` | Run the bot from source |
| `build` | `make build` | Build release binaries, archives and Docker images with GoReleaser (snapshot; needs Docker) |
| `bump-version` | `make bump-version TAG=vX.Y.Z` | Update version strings (run on a PR branch, merge, then tag) |
| `lint` | `make lint` | Run golangci-lint for code quality |
| `tidy` | `make tidy` | Clean and download go.mod dependencies |
| `vendor` | `make vendor` | Vendor dependencies |
| `test` | `make test` | Run test suite (SQLite + miniredis; `-tags testtools -race -coverprofile=coverage.out`) |
| `test-postgres-integrity` | `make test-postgres-integrity` | Run the Postgres-only integrity tests (needs `DATABASE_URL` and `ALITA_TEST_DATABASE=true`) |
| `psql-migrate` | `make psql-migrate` | Apply database migrations |
| `psql-status` | `make psql-status` | Check migration status |
| `psql-reset` | `make psql-reset` | Reset database (DANGEROUS) |
| `validate-db` | `make validate-db` | Validate database for orphaned data |
| `backup-db` | `make backup-db` | Backup database before migrations |
| `check-translations` | `make check-translations` | Detect missing translation keys and values left in English |
| `check-duplicates` | `make check-duplicates` | Check for duplicate code |
| `check-docs` | `make check-docs` | Check documentation integrity |
| `inventory` | `make inventory` | Generate the canonical command inventory (`.planning/INVENTORY.json` and `.planning/INVENTORY.md`) |
| `generate-docs` | `make generate-docs` | Generate documentation site content |
| `docs-dev` | `make docs-dev` | Start the docs dev server |

## Code Quality

### Run Linter

```bash
make lint
```

This runs golangci-lint with the project's configuration. Fix any issues before committing.

### Check Dependencies

```bash
make tidy
```

This:
- Removes unused dependencies
- Downloads missing dependencies
- Updates `go.sum` checksums

## Project Structure

```
Alita_Robot/
├── main.go              # Entry point
├── go.mod               # Go module definition
├── go.sum               # Dependency checksums
├── Makefile             # Build automation
├── .goreleaser.yaml     # GoReleaser configuration
├── sample.env           # Example environment file
├── docker-compose.yml   # Docker Compose configuration
├── .dockerignore          # Docker ignore rules
├── debug.docker-compose.yml # Debug compose configuration
├── alita/               # Main application code
│   ├── config/          # Configuration loading
│   ├── db/              # Database models and operations
│   ├── modules/         # Bot command handlers
│   ├── utils/           # Utility functions (incl. httpserver for health/metrics/webhook)
│   ├── i18n/            # Internationalization
├── migrations/          # SQL migration files
├── locales/             # Translation files
└── docs/                # Documentation
```

## Development Mode

For development, run with debug logging:

```bash
DEBUG=true make run
```

Or set in your `.env` file:

```bash
DEBUG=true
```

:::note
Debug mode increases log verbosity, disables performance monitoring, and shows detailed error stack traces. Do not use in production.
:::

## GoReleaser Configuration

The `.goreleaser.yaml` defines the build process:

```yaml
version: 2
project_name: alita_robot

builds:
  - binary: alita_robot
    env:
      - CGO_ENABLED=0
    goos:
      - darwin
      - linux
      - windows
    goarch:
      - amd64
      - arm64
    flags:
      - -trimpath
    ldflags:
      - -s -w
    mod_timestamp: "{{ .CommitTimestamp }}"
```

### Build Output

After running `make build`, binaries are created in:

```
dist/
├── alita_robot_darwin_amd64_v1/alita_robot
├── alita_robot_darwin_arm64_v8.0/alita_robot
├── alita_robot_linux_amd64_v1/alita_robot
├── alita_robot_linux_arm64_v8.0/alita_robot
├── alita_robot_windows_amd64_v1/alita_robot.exe
├── alita_robot_windows_arm64_v8.0/alita_robot.exe
├── alita_robot_<version>_{macOS,linux}_{amd64,arm64}.tar.gz
├── alita_robot_<version>_windows_{amd64,arm64}.zip
└── checksums.txt
```

## Dependencies

Key dependencies from `go.mod`:

| Package | Purpose |
|---------|---------|
| `gotgbot/v2` | Telegram Bot API client |
| `gorm.io/gorm` | ORM for database operations |
| `redis/go-redis/v9` | Redis client |
| `sirupsen/logrus` | Structured logging |
| `prometheus/client_golang` | Metrics |

## Testing

```bash
# Run linter (recommended before commits)
make lint

# Run test suite
make test

# Test manually with a test bot
DEBUG=true make run
```

## Hot Reload (Development)

:::tip
Use `air` for automatic reloading during development so you do not need to manually restart the bot after every code change.
:::

```bash
# Install air
go install github.com/air-verse/air@latest

# Create .air.toml
air init

# Run with hot reload
air
```

Example `.air.toml`:

```toml
root = "."
tmp_dir = "tmp"

[build]
cmd = "go build -o ./tmp/alita_robot ."
bin = "tmp/alita_robot"
include_ext = ["go"]
exclude_dir = ["tmp", "vendor", "docs"]
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes
4. Run `make lint` and fix any issues
5. Submit a pull request

See [Contributing Guide](/contributing/) for more details.

## Troubleshooting

### Go version too old

```
go: go.mod requires go >= 1.26
```

Update Go to version 1.26 or higher.

### golangci-lint not found

```bash
# Install golangci-lint
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.14.0

# Add to PATH
export PATH=$PATH:$(go env GOPATH)/bin
```

### Linter cannot read Go export data

If linting reports `export data version 5 is greater than maximum supported version 4`
with Go 1.27.2, upgrade golangci-lint to v2.14.0 or newer. Keep both CI lint steps
and the pre-commit hook on the same version. This is a linter compatibility error,
not a broken standard-library import.

### Module download errors

```bash
# Clear module cache
go clean -modcache

# Download dependencies
make tidy
```

### Build fails with CGO errors

:::caution
The bot is built with `CGO_ENABLED=0` for static binaries. If you explicitly need CGO, you must have a C compiler and platform-specific libraries installed.
:::

```bash
CGO_ENABLED=1 go build -o alita_robot .
```