# Install Hiro

**URL:** https://heroiclabs.com/docs/hiro/concepts/getting-started/install/
**Summary:** Learn how to set up Hiro on your Nakama server.
**Keywords:** install hiro
**Categories:** hiro, install, getting-started

---


# Install Hiro

Hiro is a game development kit that extends Nakama with powerful systems for economies, progression, social features, and more. This guide walks you through installing Hiro on your Nakama server and getting it running locally.

## System requirements

This guide assumes you're running Nakama with Docker, which is the recommended approach for getting started quickly.

You'll need:

- A compatible version of [Nakama](../../../../nakama/getting-started/install/docker/)
- [Go](https://go.dev/doc/install) for building your server runtime
- [Docker and Docker Compose](https://docs.docker.com/get-docker/) for running Nakama locally

### Compatibility matrix

Use the following table to find the required Nakama version for your Hiro release:

{{< table name="hiro.getting-started.install.hiro-nakama-version" initial="10" >}}

## Obtaining Hiro

Hiro is available exclusively from Heroic Labs. [Contact us](mailto:contact@heroiclabs.com) to request access. We'll provide you with:

- Server binaries
- Client SDKs
- License key for your project
- Access to dedicated engineering support

## Install Hiro on the server

### Extract Hiro binaries

After receiving your Hiro distribution archive (`Hiro-<version>.zip`), extract it to find the server binaries.

1. Unzip the archive:

```bash
unzip Hiro-<version>.zip
cd Hiro-<version>/server
```

2. Copy the binary files to your Nakama server directory:

```bash
cp hiro*.bin /path/to/your/nakama-project/
```

You should now have files like `hiro-linux-arm64.bin`, `hiro-darwin-arm64.bin`, etc. in your project directory.

### Configure Docker

Update your Docker configuration to copy Hiro binaries into your container and set up the recommended environment.

#### Update your Dockerfile

Replace your existing `Dockerfile` with this configuration:

```dockerfile
FROM heroiclabs/nakama-pluginbuilder:3.27.0 AS builder

ENV GO111MODULE on
ENV CGO_ENABLED 1

WORKDIR /backend
COPY . .

RUN go build --trimpath --buildmode=plugin -o ./backend.so

FROM heroiclabs/nakama:3.27.0

COPY --from=builder /backend/backend.so /nakama/data/modules
COPY --from=builder /backend/local.yml /nakama/data/
COPY --from=builder /backend/*.json /nakama/data/modules

# Copy Hiro binaries
COPY --from=builder /backend/hiro*.bin /nakama/data/modules
```

This Dockerfile builds your Go runtime as a plugin and copies both your code and the Hiro binaries into the Nakama container.

#### Update your docker-compose.yml

Replace your existing `docker-compose.yml` with this recommended setup:

```yml
services:
  postgres:
    container_name: game_backend_postgres
    environment:
      - POSTGRES_DB=nakama
      - POSTGRES_PASSWORD=localdb
    expose:
      - "8080"
      - "5432"
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres", "-d", "nakama"]
      interval: 3s
      timeout: 3s
      retries: 5
    image: postgres:12.2-alpine
    ports:
      - "5432:5432"
      - "8080:8080"
    volumes:
      - data:/var/lib/postgresql/data
  nakama:
    build: .
    container_name: game_backend
    depends_on:
      postgres:
        condition: service_healthy
    entrypoint:
      - "/bin/sh"
      - "-ecx"
      - >
        /nakama/nakama migrate up --database.address postgres:localdb@postgres:5432/nakama &&
        exec /nakama/nakama --config /nakama/data/local.yml --database.address postgres:localdb@postgres:5432/nakama
    expose:
      - "7349"
      - "7350"
      - "7351"
    healthcheck:
      test: ["CMD", "/nakama/nakama", "healthcheck"]
      interval: 10s
      timeout: 5s
      retries: 5
    links:
      - "postgres:db"
    ports:
      - "7349:7349"
      - "7350:7350"
      - "7351:7351"
    restart: unless-stopped
volumes:
  data:
```

### Set up your Go runtime

Create your server-side code that initializes Hiro and configures which systems you want to use.

#### Add Hiro to your Go dependencies

Run this command to add Hiro as a dependency:

```bash
go get github.com/heroiclabs/hiro@latest
```

#### Configure your license key

Add your `HIRO_LICENSE` key to your `local.yml` config file:

```yml
runtime:
  env:
    - "ENV=dev1"
    - "HIRO_LICENSE=<your-license-key>"
```

Replace `<your-license-key>` with the license key provided by Heroic Labs.

#### Create your main.go file

Your `main.go` file needs to initialize Hiro with your license key and configure which game systems you want to use. This code will:

- Validate your license key from environment variables.
- Detect your platform and select the correct Hiro binary.
- Initialize Hiro with common game systems (base, inventory, economy, achievements, leaderboards, and stats).

Create a `main.go` file in your project root:

```go
package main

import (
	"context"
	"database/sql"
	"errors"
	"fmt"
	osruntime "runtime"

	"github.com/heroiclabs/hiro"
	"github.com/heroiclabs/nakama-common/runtime"
)

//goland:noinspection GoUnusedExportedFunction
func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
	// Get environment variables from Nakama config
	props, ok := ctx.Value(runtime.RUNTIME_CTX_ENV).(map[string]string)
	if !ok {
		return errors.New("invalid context runtime env")
	}

	env, ok := props["ENV"]
	if !ok || env == "" {
		return errors.New("'ENV' key missing or invalid in env")
	}
	logger.Info("Using env named %q", env)

	hiroLicense, ok := props["HIRO_LICENSE"]
	if !ok || hiroLicense == "" {
		return errors.New("'HIRO_LICENSE' key missing or invalid in env")
	}

	// Select the correct binary for your platform
	binPath := "hiro.bin"
	switch osruntime.GOOS {
	case "darwin":
		switch osruntime.GOARCH {
		case "arm64":
			binPath = "hiro-darwin-arm64.bin"
		}
	case "linux":
		switch osruntime.GOARCH {
		case "arm64":
			binPath = "hiro-linux-arm64.bin"
		}
	}
	logger.Info("CPU os %q arch %q detected with binPath set as %q", osruntime.GOOS, osruntime.GOARCH, binPath)

	// Initialize Hiro with the systems you want to use
	systems, err := hiro.Init(ctx, logger, nk, initializer, binPath, hiroLicense,
		hiro.WithBaseSystem(fmt.Sprintf("base-system-%s.json", env), true),
		hiro.WithInventorySystem(fmt.Sprintf("base-inventory-%s.json", env), true),
		hiro.WithEconomySystem(fmt.Sprintf("base-economy-%s.json", env), true),
		hiro.WithAchievementsSystem(fmt.Sprintf("base-achievements-%s.json", env), true),
		hiro.WithLeaderboardsSystem(fmt.Sprintf("base-leaderboards-%s.json", env), true),
		hiro.WithStatsSystem(fmt.Sprintf("base-stats-%s.json", env), true))
	if err != nil {
		return err
	}
	_ = systems

	return nil
}
```

### Create system config files

Hiro systems are configured using JSON files. Create these files in your project root:

- `base-system-dev1.json`
- `base-inventory-dev1.json`
- `base-economy-dev1.json`
- `base-achievements-dev1.json`
- `base-leaderboards-dev1.json`
- `base-stats-dev1.json`

For now, create empty JSON objects in each file:

```bash
echo '{}' > base-system-dev1.json
echo '{}' > base-inventory-dev1.json
echo '{}' > base-economy-dev1.json
echo '{}' > base-achievements-dev1.json
echo '{}' > base-leaderboards-dev1.json
echo '{}' > base-stats-dev1.json
```

You'll configure these files later based on your game's requirements. See the individual system documentation for configuration options.

### Download dependencies and build

Install all Go dependencies:

```bash
go mod tidy
go mod vendor
```

Build and run your server with Docker Compose:

```bash
docker compose up --build
```

The first build takes a few minutes. Docker will:

1. Build your Go plugin
2. Create the Nakama container with your code and Hiro
3. Start PostgreSQL
4. Run database migrations
5. Start Nakama

### Verify installation

You'll know Hiro is installed correctly when you see logs like these:

```bash
game_backend | {"level":"info","ts":"2024-06-25T12:02:35.254Z","caller":"server/runtime.go:709","msg":"Registered Go runtime RPC function invocation","id":"rpc_id_base_set_device_prefs"}
game_backend | {"level":"info","ts":"2024-06-25T12:02:35.254Z","caller":"server/runtime.go:709","msg":"Registered Go runtime RPC function invocation","id":"rpc_id_inventory_grant"}
game_backend | {"level":"info","ts":"2024-06-25T12:02:35.254Z","caller":"server/runtime.go:709","msg":"Registered Go runtime RPC function invocation","id":"rpc_id_economy_donation_claim"}
```

These logs show that Hiro's RPC functions are registered and ready to use.

Test your server is responding:

```bash
curl http://localhost:7350
```

You should see a JSON response with Nakama server information.

## Install Hiro client SDKs

After setting up Hiro on your server, you'll need a client SDK to connect to it from your game. Hiro provides client SDKs for multiple platforms:

| Platform   | Description                                                  | Documentation                                                 |
| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------- |
| Unity      | Package containing DLLs for Unity projects                   | [Unity client](../../../unity/getting-started/nakama-system/) |
| Unreal     | Plugin for Unreal Engine with full C++ and Blueprint support | [Unreal client](../../../unreal/getting-started/hiro-client/) |
| C++        | Cross-platform C++ library for custom engines                | [C++ client](../../../cpp/achievements/)                      |
| TypeScript | TypeScript library for web and Node.js                       | [TypeScript client](../../../typescript/getting-started/)     |
| Dart       | Dart client library for Flutter and Dart applications        | [Dart client](../../../dart/getting-started/)                 |
| Godot      | Client for Godot Engine projects                             | [Godot client](../../../godot/getting-started/)               |
| Python     | Client for Python projects                                   | [Python client](../../../python/getting-started/)             |

## Post installation

### Upgrade Hiro

To upgrade to a new version of Hiro:

1. Download the new Hiro release from Heroic Labs.
2. Replace the binary files in your server project:

   ```bash
   cp Hiro-<new-version>/server/hiro*.bin /path/to/your/nakama-project/
   ```

3. Update your Go dependency to match the server version:

   ```bash
   go get github.com/heroiclabs/hiro@v<hiro-version>
   ```

4. Check the [version compatibility](#version-compatibility) table in the System requirements section to see which Nakama version your new Hiro version requires

5. Update your `Dockerfile` to use the matching Nakama version:

   ```dockerfile
   FROM heroiclabs/nakama-pluginbuilder:<nakama-version> AS builder
   # ...
   FROM heroiclabs/nakama:<nakama-version>
   ```

6. Download updated dependencies:

   ```bash
   go mod vendor
   ```

7. Upgrade your client SDK to the matching version using the same installation process as before

8. Rebuild and run your server:
   ```bash
   docker compose up --build
   ```

### Upgrade on Heroic Cloud

If you're using Heroic Cloud for hosting:

1. Push your latest code to your repository.
2. Go to your builder's edit page in Heroic Cloud.
3. Select the matching `Nakama Image` version from the dropdown.
4. Click **Update**.
5. Run a new container build.

## Next steps

Now that Hiro is installed, here's what to do next:

1. [Configure your game systems](../configurations/) to populate the JSON configuration files with your game's economy, achievements, and other system settings.
2. [Explore sample projects](../../../../sample-projects/) for complete ready-to-run examples that demonstrate Hiro in action.