Contractless/docs/LINUX_INSTALLATION.md

# Linux Installation

This guide explains how to build, install, configure, and start a Contractless testnet node on Linux.

Contractless can be run from the build folder, from a user-owned install folder, or from a system path such as `/usr/bin`. For public testnet nodes, use a stable run path and a stable `settings.ini` location so runtime data does not move unexpectedly between starts.

## Build Flags

The default build target is testnet:

```bash
cargo build --release
```

The same testnet build can be requested explicitly:

```bash
cargo build --release --features testnet
```

Mainnet has its own feature flag:

```bash
cargo build --release --no-default-features --features mainnet
```

Mainnet is not active during the testnet phase. Use the testnet binary unless mainnet has been officially enabled.

After building, release binaries are written to:

```text
target/release/
```

The testnet node binary is:

```text
target/release/contractless-testnet
```

## PostgreSQL Installation

**Do not expose PostgreSQL to the public Internet. The PostgreSQL port should not be publicly accessible.** Contractless needs a public RPC port for peers, but PostgreSQL should stay local or private, usually on `127.0.0.1`. Do not open PostgreSQL port `5432` in your router, cloud firewall, VPS firewall, or host firewall.

The installer only supports Linux systems where this `apt-get` flow is valid. If your Linux distribution does not use `apt-get`, [create the PostgreSQL database manually](src/branch/main/docs/POSTGRES.md).

Contractless uses PostgreSQL for transaction lookup and mempool-style records. The node creates and updates its own tables during startup, but PostgreSQL itself must exist first with a database, user, password, and permissions.

Build the release binaries first:

```bash
cargo build --release
```

Run the PostgreSQL installer with root access:

```bash
sudo ./target/release/postgres_installer
```

The Linux installer:

- checks whether `psql` is installed
- runs `apt-get update` when PostgreSQL is missing
- installs PostgreSQL with `apt-get install -y postgresql`
- updates local password authentication in `pg_hba.conf` when needed
- reloads PostgreSQL
- creates the configured database user
- creates the configured database
- prints the `[Postgres]` settings block to paste into `settings.ini`

For testnet builds, paste the printed values into `[Postgres-Testnet]` in the active `settings.ini`.

Example:

```ini
[Postgres-Testnet]
host = 127.0.0.1
port = 5432
user = contractless
password = your_postgres_password_here
dbname = contractless_db
```

## Run Path and Settings Location

The node loads `settings.ini` in this order:

1. `--config <path>`
2. `SETTINGS_PATH` environment variable
3. `./settings.ini`
4. `settings.ini` beside the executable
5. `/etc/contractless/settings.ini`

For a stable Linux install, use:

```text
/etc/contractless/settings.ini
```

Create the config directory:

```bash
sudo mkdir -p /etc/contractless
```

Move the repository settings file:

```bash
sudo mv ./settings.ini /etc/contractless/settings.ini
```

The node also scopes runtime folders by network internally, so testnet data and mainnet data do not collide.

Important runtime paths:

| Setting | Purpose |
| --- | --- |
| `BLOCK_PATH` | Saved block files |
| `TORRENT_PATH` | Torrent metadata and staged torrents |
| `DB_PATH` | sled state and Linux PID file |
| `BALANCE_SHEET` | Balance files |
| `LOG_PATH` | Runtime logs |
| `WALLET_PATH` | Wallet directory |
| `WALLET_NAME` | Wallet filename |

## Copy Binaries

Copy the testnet node binary into a system path:

```bash
sudo cp ./target/release/contractless-testnet /usr/bin/
```

Copy the PostgreSQL installer if you want it available system-wide:

```bash
sudo cp ./target/release/postgres_installer /usr/bin/
```

Copy wallet tools:

```bash
sudo cp ./target/release/create_new_wallet /usr/bin/
sudo cp ./target/release/recreate_wallet /usr/bin/
sudo cp ./target/release/recreate_wallet_from_image /usr/bin/
sudo cp ./target/release/register_wallet /usr/bin/
sudo cp ./target/release/verify_address /usr/bin/
```

Copy transaction and lookup tools as needed:

```bash
sudo cp ./target/release/create_transfer_tx /usr/bin/
sudo cp ./target/release/broadcast_transaction /usr/bin/
sudo cp ./target/release/lookup_height /usr/bin/
sudo cp ./target/release/lookup_transaction /usr/bin/
sudo cp ./target/release/lookup_remote_balance /usr/bin/
```

You can copy any additional tools from `target/release` using the same pattern.

## Start the Node

Start the testnet node:

```bash
contractless-testnet
```

On Linux, the node prompts for the wallet decryption key and then detaches into the background by default.

Use a specific settings file:

```bash
contractless-testnet --config /etc/contractless/settings.ini
```

## Startup Flags

Linux node flags:

| Flag | Purpose |
| --- | --- |
| `--config <path>` | Load a specific `settings.ini` file |
| `--status` | Check whether the daemonized node is running |
| `--stop` | Stop the daemonized node |

Check daemon status:

```bash
contractless-testnet --status
```

Stop the daemon:

```bash
contractless-testnet --stop
```

The Linux daemon PID file is stored under the active network's `DB_PATH`.

## Updating a Node

Stop the node:

```bash
contractless-testnet --stop
```

Pull the latest source:

```bash
git pull
```

Rebuild:

```bash
cargo build --release
```

Copy the updated binary:

```bash
sudo cp ./target/release/contractless-testnet /usr/bin/
```

Start the node:

```bash
contractless-testnet
```