> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Bootstrap a server as an orun node over SSH

> Provision a remote Linux server as an orun node using orun bootstrap, covering prerequisites, interactive prompts, and what bootstrap does on the remote host.

The `orun bootstrap` command provisions a remote Linux server as an orun node entirely over SSH. Run it once from your local machine; after that the node operates autonomously, pulling its desired state from your manifest Git repository with no ongoing SSH access required.

## Prerequisites

Before you run `orun bootstrap`, confirm you have the following:

* A Linux server reachable over SSH (public IP or hostname)
* Your SSH private key configured and accessible locally (default: `~/.ssh/id_ed25519`)
* The `orun` binary installed on your **local** machine
* Docker or Podman on the target server — orun installs either one automatically if neither is detected

<Steps>
  <Step title="Create or navigate to your manifest repository">
    Bootstrap must be run from the root of your manifest Git repository. If you do not have one yet, create it now:

    ```bash theme={null}
    git init my-manifests
    cd my-manifests
    ```

    The repository layout orun expects is:

    ```
    deployments/
    nodes/
    services/
    ```

    Commit an initial structure (even empty directories with `.gitkeep` files) and push to your remote before proceeding, so the node can clone it after bootstrap.
  </Step>

  <Step title="Run the interactive bootstrap">
    From the root of your manifest repository, run:

    ```bash theme={null}
    orun bootstrap
    ```

    orun prompts you for the following values in order:

    | Prompt                          | Required | Default             |
    | ------------------------------- | -------- | ------------------- |
    | Node name (e.g. `web-01`)       | Yes      | —                   |
    | Host (IP or hostname)           | Yes      | —                   |
    | SSH user                        | No       | `root`              |
    | SSH private key path            | No       | `~/.ssh/id_ed25519` |
    | Manifest git repository URL     | Yes      | —                   |
    | Git branch                      | No       | `main`              |
    | Poll interval (e.g. `5s`, `1m`) | No       | `5s`                |
    | Data directory on the node      | No       | `/opt/orun/`        |

    Press Enter to accept a default value. Required fields repeat until you supply a value.

    When the prompts are complete, orun writes the node manifest to `nodes/<name>.yaml` and immediately begins the bootstrap process.
  </Step>

  <Step title="Bootstrap from an existing manifest">
    If you already have a node manifest (for example, when adopting a second node), pass the path directly:

    ```bash theme={null}
    orun bootstrap nodes/web-01.yaml
    ```

    orun loads the manifest, applies defaults to any omitted fields, validates the spec, and proceeds to provision the node.
  </Step>

  <Step title="Understand what bootstrap does on the node">
    During the bootstrap process, orun:

    1. Connects to the node over SSH using the configured key
    2. Detects or installs Docker or Podman
    3. Copies the `orun` binary to the node
    4. Creates and enables a `systemd` service (`orun start`)
    5. Verifies the service is running

    The `orun start` service is configured with `--node-name`, `--repo`, and the other flags derived from the node manifest, so the node knows which Git repository and branch to track.
  </Step>

  <Step title="Commit the node manifest">
    After a successful bootstrap, the node manifest lives at `nodes/<name>.yaml` in your manifest repository. Commit and push it:

    ```bash theme={null}
    git add nodes/web-01.yaml
    git commit -m "Add web-01 node manifest"
    git push
    ```

    <Tip>
      Committing the manifest means bootstrapping any additional node in the future is a single command: `orun bootstrap nodes/<name>.yaml`.
    </Tip>
  </Step>

  <Step title="Verify the node service is running">
    SSH into the node and check the systemd service:

    ```bash theme={null}
    ssh root@<node-ip> 'systemctl status orun'
    ```

    You should see the service in the `active (running)` state. You can also tail the structured JSON logs:

    ```bash theme={null}
    ssh root@<node-ip> 'journalctl -u orun -f'
    ```
  </Step>
</Steps>

<Note>
  After a successful bootstrap, no ongoing SSH access is required. The node polls the manifest Git repository on its own, reconciling any changes you push to the tracked branch.
</Note>

<CardGroup cols={2}>
  <Card title="Deploy your first app" icon="rocket" href="/guides/deploy-your-first-app">
    Write a Deployment manifest and watch orun pull and run it automatically.
  </Card>

  <Card title="Enable HTTPS ingress" icon="lock" href="/guides/ssl-and-ingress">
    Expose a deployment on a custom domain with automatic TLS.
  </Card>
</CardGroup>