# Builder Setup Guide

Set up a builder server to compile Android apps. Required for app builds to work.

#### On this page

- What is a Builder?
- Default Free Builder
- Server Requirements
- Option A: Use Prebuilt Binary
- Option B: Build from Source
- Running the Builder
- Running with PM2
- Registering in Appy

## What is a Builder?

A builder server is a dedicated machine that compiles apps for your users. The builder is platform-agnostic and designed to support multiple platforms (Android, iOS, Windows, Linux, Mac) in the future. Currently, only Android is supported.

- Runs separately from your main Appy installation
- Can be on the same server (for testing) or a dedicated server (recommended for production)
- Two installation options: prebuilt binaries (quick start) or build from source (full control)
- Requires Java and Android SDK to compile Android apps
- Automatically fetches pending builds from your Appy installation

### Builder Package Structure

The `Builder/` folder contains two directories:

    Builder/
    ├── src/                    # Full source code (build your own binary)
    │   ├── app.go
    │   ├── Makefile
    │   ├── templates/
    │   └── internal/
    └── prebuilt/               # Ready-to-run binaries
        ├── appy-builder-linux  # Linux AMD64
        ├── appy-builder-arm64  # Linux ARM64
        ├── appy-builder-macos  # macOS ARM64
        ├── templates/
        └── storage/

Note: Without a builder server, app builds will remain in "pending" status and never complete.

## Default Free Builder

Appy comes with a Default Free Builder hosted by Titan Systems. This builder is automatically configured during installation and requires no manual setup.

Property | Value
--- | ---
Name | Default Builder
URL | `https://appy-builder.titansystems.ph`
Port | 443 (HTTPS)
Credit Cost | 1 credit per build
Max Queue | 5 concurrent builds
Platforms | All active platforms (Android WebView, etc.)

### How It Works

- Automatic Authentication: The default builder uses your purchase code for authentication. No server key configuration is needed.
- Credit System: Each build deducts credits from your user's plan allocation. Plans define monthly build credits (e.g., 100 credits/month for Pro).
- Queue Management: Builds are queued and processed in order. The builder supports up to 5 concurrent builds.
- No Setup Required: The default builder is pre-configured and ready to use immediately after installation.

Good News! If you're using the default builder, you can skip the rest of this guide. Your builds will work out of the box. Continue below only if you want to set up your own custom builder.

### When to Use a Custom Builder

Consider setting up your own builder if:

- You need faster build times with dedicated resources
- You want full control over the build environment
- You're running a high-volume operation with many concurrent builds
- You need to customize the build process or templates

## Server Requirements (Custom Builder)

The builder server needs the following specifications:

Requirement | Minimum | Notes
--- | --- | ---
OS | Ubuntu 20.04+ | Other Linux distros may work
RAM | 4GB | 8GB recommended for multiple workers
Storage | 20GB | For SDK and build artifacts
Java + Android SDK | Java 17, API 35 | See Android SDK
Node.js | 18+ | For PM2 process manager (optional)
Go | 1.21+ | Only if building from source (optional)

Before You Continue: Complete the Android SDK Guide first. Java 17 and Android SDK must be installed and configured before running the builder.

## Option A: Use Prebuilt Binary

The fastest way to get started. Use the pre-compiled binaries included in the `Builder/prebuilt/` folder.

1

#### Upload Prebuilt Files

Upload the entire `Builder/prebuilt/` folder to your server. A common location is `/opt/appy-builder/`.

    scp -r Builder/prebuilt/* user@server:/opt/appy-builder/

This includes the binary, templates/, and storage/ directories.

2

#### Make Executable

    chmod +x appy-builder-linux

Use `appy-builder-arm64` for ARM64 servers or `appy-builder-macos` for macOS.

Ready! Skip to Running the Builder to start the server.

## Option B: Build from Source

Build your own binary from the full source code. Gives you complete control over the build process and allows customization.

Requirement: Go 1.21 or later must be installed on your server.

1

#### Install Go (if not installed)

    # Ubuntu/Debian
    sudo apt install golang-go -y

    # Verify installation
    go version

Or download from go.dev/dl

2

#### Upload Source Code

Upload the `Builder/src/` folder to your server:

    scp -r Builder/src/* user@server:/opt/appy-builder/

3

#### Build the Binary

Navigate to the directory and build:

    cd /opt/appy-builder

    # Build for your platform
    make build-linux    # Linux AMD64
    make build-arm64    # Linux ARM64
    make build-macos    # macOS ARM64

Binary will be created in `dist/` folder.

4

#### Create Runtime Directories

    make setup

Run the binary directly from the dist/ folder: `./dist/appy-builder-linux`

### Build Commands Reference

Command | Description
--- | ---
`make build` | Build development binary
`make build-linux` | Build for Linux AMD64
`make build-arm64` | Build for Linux ARM64
`make build-macos` | Build for macOS ARM64
`make test` | Run all tests
`make clean` | Clean build artifacts
`make setup` | Create required directories

## Running the Builder

Once you have the binary ready (from Option A or B), run the builder:

1

#### Test Run (Manual)

Run the builder manually to test:

    ./appy-builder-linux --key="your-secret-key" --site-url="https://your-appy-domain.com"

### Available Flags

Flag | Description | Default
--- | --- | ---
`--key` | Server authentication key (must match Appy admin panel) | Required
`--site-url` | URL of your Appy installation | Required
`--port` | Port to listen on | 8080
`--host` | Host to bind to | 0.0.0.0
`--build-workers` | Number of concurrent builds | 1
`--debug` | Enable debug logging | false

Important: The `--key` value must exactly match the Server Key you enter in the Appy admin panel when registering this builder.

## Running with PM2 (Background)

For production, use PM2 to run the builder in the background with automatic restarts.

1

#### Start Builder with PM2

    pm2 start ./appy-builder-linux --name "appy-builder" -- --key="your-secret-key" --site-url="https://your-appy-domain.com"

If built from source, use: `pm2 start ./dist/appy-builder-linux --name "appy-builder" -- ...`

2

#### Enable Auto-Start on Reboot

Generate the startup script:

    pm2 startup

Save the current process list:

    pm2 save

### Useful PM2 Commands

Command | Description
--- | ---
`pm2 status` | Check if builder is running
`pm2 logs appy-builder` | View builder logs
`pm2 restart all` | Restart the builder
`pm2 stop all` | Stop the builder

## Registering in Appy

Once the builder is running, you need to register it in the Appy admin panel.

1

#### Go to Builders

Navigate to Admin > Builders in your Appy dashboard.

2

#### Add New Builder

Click the Add Builder button.

3

#### Enter Builder Details

- Name: A friendly name (e.g., "Production Builder")
- URL: The server IP or domain (e.g., `http://192.168.1.100`)
- Port: The port from `--port` flag (default: 8080)
- Server Key: The key from `--key` flag
- Platform: Android
- Status: Active

4

#### Test the Builder

Create a test app and trigger a debug build. Check that the build completes successfully.

Done! Your builder is now set up and ready to compile apps. Continue to the Admin Settings to configure your platform.

© 2026 Titan Systems. All Rights Reserved.