# Getting Started

This page walks through building, configuring, and running your first `podrun up` to deploy a compose project to remote Podman.

## Prerequisites

| Requirement | Where | Notes |
|---|---|---|
| Go 1.25.1+ | Build host | Taken from `go.mod` |
| C compiler (`CGO_ENABLED=1`) | Build host (API server) | `github.com/mattn/go-sqlite3` requires cgo |
| `sshpass`, `rsync`, `ssh`, `curl`, `unzip` | Local (CLI) | `CheckRelyPackages()` installs them when missing |
| macOS or Linux | Local (CLI) | Other operating systems abort when packages are missing |
| SSH password login | Remote host | The CLI connects through `sshpass` |
| Podman + `podman compose` | Remote host | Container runtime |
| Write access to `/home/podrun` | Remote host | Remote project folders are always created here |

## Installation

```bash
git clone https://github.com/pardnchiu/PodRun.git
cd PodRun
go build -o podrun ./cmd/cli
CGO_ENABLED=1 go build -o podrun-api ./cmd/api
```

For the CLI alone, use `go install`; the resulting binary is named `cli` after the package directory:

```bash
go install github.com/pardnchiu/PodRun/cmd/cli@latest
```

## Configure the Remote Connection

On startup the CLI reads three required variables from `.env` in the current working directory and aborts if any is missing:

```dotenv
PODRUN_SERVER=192.168.1.100
PODRUN_USERNAME=podrun
PODRUN_PASSWORD=yourpassword
```

See [Configuration](/configuration) for every variable.

## Start the API Server

The API server reads `sql/create.sql` through a relative path, so run it from the repo root. The CLI always targets `localhost:8080`, so both must run on the same machine.

```bash
cd PodRun
./podrun-api
```

## First Deployment

Run inside a project folder that contains `docker-compose.yml` or `docker-compose.yaml`:

```bash
cd ~/projects/my-app
podrun up -d
```

In `-d` mode the command prints container port mappings, the Pod ID and name, and the local hostname and IP. Day-to-day commands:

```bash
podrun ps
podrun logs -f
podrun down
podrun clear
```

## Next Steps

- [Core Concepts](/core-concepts): how the UID and remote folder are derived
- [File Sync](/file-sync): diff preview and exclude rules
- [CLI Reference](/cli-reference): every command and flag