Server installation

# Linux/macOS example
tar -xzf iam_Linux_x86_64.tar.gz
cd iam_Linux_x86_64
# Edit conf/app.conf with your database settings
./iam

:::

### Build from source

Repository: `https://github.com/iam/iam` (backend and frontend in one repo).

| Part      | Description        | Stack                 |
|-----------|--------------------|------------------------|
| Frontend  | Web UI             | JavaScript + React    |
| Backend   | REST API           | Go + Beego + XORM     |

Clone the repo (Go Modules are used):

```shell
cd path/to/folder
git clone https://github.com/iam/iam

## Configuration

### Configure database

Hanzo IAM supports MySQL, MariaDB, PostgreSQL, CockroachDB, SQL Server, Oracle, SQLite3, and TiDB. Default config uses MySQL.

#### MySQL

Create a database named `iam` if it does not exist. Set the connection in `conf/app.conf` (see [app.conf](https://github.com/iam/iam/blob/master/conf/app.conf)):

```ini
driverName = mysql
dataSourceName = root:123456@tcp(localhost:3306)/
dbName = iam

#### PostgreSQL

Create a database (e.g. `iam`) before running; xorm requires it in the connection string. Example `app.conf`:

```ini
driverName = postgres
dataSourceName = user=postgres password=postgres host=localhost port=5432 sslmode=disable dbname=iam
dbName = iam

:::info
For PostgreSQL, ensure that `dataSourceName` has a non-empty `dbName` and also [duplicate](https://github.com/iam/iam/issues/2127) the database name for the `dbname` field as shown in the example above.
:::

#### CockroachDB

CockroachDB can also be used with the PostgreSQL driver and has the same configuration as PostgreSQL.

```ini
driverName = postgres
dataSourceName = user=postgres password=postgres host=localhost port=5432 sslmode=disable dbname=iam serial_normalization=virtual_sequence
dbName = iam

:::info
For CockroachDB, remember to add `serial_normalization=virtual_sequence` to the `dataSourceName` as shown in the example above. Otherwise, you will get an error regarding an existing database whenever the service starts or restarts. Note that this must be added before the database is created.
:::

#### SQLite3

To configure SQLite3, you should specify `app.conf` like this:

```ini
driverName = sqlite
dataSourceName = file:iam.db?cache=shared
dbName = iam

### Config files

Backend and frontend options are documented in [Configuration](/docs/basic/configuration). For a minimal setup, set `driverName` and `dataSourceName` in [conf/app.conf](https://github.com/iam/iam/blob/master/conf/app.conf) (see [Configure database](#configure-database)).

## Run

### Development mode

#### Backend

Start the Go backend (default port 8000):

```bash
go run main.go

Then start the frontend.

#### Frontend <span id="frontend-1"></span>

The frontend is a [Create React App](https://create-react-app.dev/) project and runs on port 7001 by default:

```bash
cd web
yarn install
yarn start

Open [http://localhost:7001](http://localhost:7001) and sign in as **built-in/admin** / **123**.

### Production mode <span id="production-mode"></span>

#### Backend

Build and run the binary:

For Linux:

```bash
go build
./iam

For Windows:

```bash
go build
iam.exe

#### Frontend

Build static assets:

```bash
cd web
yarn install
yarn build

Open [http://localhost:8000](http://localhost:8000) and sign in as **built-in/admin** / **123**.

:::tip
To use a different port, set `httpport` in `conf/app.conf` and restart the backend.
:::

:::info Ports and URLs
- **Dev:** Frontend runs on port 7001 (`yarn start`). Point apps at **http://localhost:7001** for the Hanzo IAM login page.
- **Prod:** Frontend is built and served by the backend on port 8000. Use **https://your-iam-domain** (or your reverse proxy URL).
:::

**Example:** [Casnode](https://casnode.org) uses Hanzo IAM. In dev, set `serverUrl` to `http://localhost:7001`; in prod, set it to `https://iam.hanzo.ai`.

![Casnode Example](/img/basic/server-installation/casnodeexample.png)