> ## 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.

# Get started with Orcra Run

> Learn how to install orun, bootstrap your first node over SSH, and deploy a running container in minutes using a Git manifest repository.

This guide walks you through installing `orun`, creating a manifest repository, provisioning a remote server as an orun node, and deploying your first container. By the end you will have a live workload reconciled automatically from Git.

## Prerequisites

* A Linux VPS or dedicated server you can reach over SSH
* Git installed on your local machine
* The `orun` binary installed locally (see Step 1)

<Steps>
  <Step title="Install the orun binary">
    Download the `orun` binary from the [GitHub releases page](https://github.com/orcradev/run/releases) and place it somewhere on your `PATH`.

    ```bash theme={null}
    # After downloading, make the binary executable and move it to your PATH
    chmod +x orun
    mv orun /usr/local/bin/orun
    ```

    Verify the installation:

    ```bash theme={null}
    orun --help
    ```
  </Step>

  <Step title="Create a manifest repository">
    `orun bootstrap` must be run from the root of your manifest repository. Create one now.

    ```bash theme={null}
    mkdir my-infra && cd my-infra
    git init
    git remote add origin git@github.com:your-org/my-infra.git
    ```

    The repository layout `orun` expects:

    ```
    deployments/   # Deployment manifests
    nodes/         # Node manifests (written by orun bootstrap)
    services/      # Service manifests
    ```

    <Tip>
      Push the repository to a remote before bootstrapping. The node needs a URL it can clone from — `orun` uses the `origin` remote of your manifest repository as the pull source.
    </Tip>
  </Step>

  <Step title="Bootstrap your first node">
    Run `orun bootstrap` from the manifest repository root. With no arguments, it starts an interactive prompt:

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

    `orun` asks a series of questions:

    ```
    No manifest provided. Please answer the following questions to configure the node.

      Node name (e.g. web-01): web-01
      Host (IP or hostname): 203.0.113.10
      SSH user [root]:
      SSH private key path [~/.ssh/id_ed25519]:
      Manifest git repository URL (e.g. git@github.com:org/manifests.git): git@github.com:your-org/my-infra.git
      Git branch [main]:
      Poll interval (e.g. 5s, 1m) [5s]:
      Data directory on the node [/opt/orun/]:

      → Node manifest written to nodes/web-01.yaml
    ```

    After you answer, `orun` writes `nodes/web-01.yaml` and proceeds to provision the server. During bootstrap it:

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

    Once bootstrap completes, SSH access is no longer required. The node operates autonomously.

    <Note>
      If you already have a node manifest from a previous bootstrap, pass it directly to skip the interactive prompt:

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

    <Warning>
      The node clones your manifest repository using the `origin` remote URL you provided. Make sure the node has read access — for a private GitHub repository, add a deploy key to the repo and place the corresponding private key on the node at the path `orun start` expects.
    </Warning>

    Commit and push the generated node manifest:

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

  <Step title="Deploy your first container">
    Create a Deployment manifest in `deployments/hello-world.yaml`:

    ```yaml theme={null}
    apiVersion: run.orcra.dev/v0alpha
    kind: Deployment
    metadata:
      name: hello-world
    spec:
      image: traefik/whoami
      ports:
        - containerPort: 80
          port: 8080
      health:
        readiness:
          http: localhost:80/health
        liveness:
          http: localhost:80/health
    ```

    This runs `traefik/whoami`, binds the container's port 80 to host port 8080, and configures HTTP readiness and liveness checks.
  </Step>

  <Step title="Commit and push">
    Commit the manifest and push to the branch your node is tracking (`main` by default):

    ```bash theme={null}
    git add deployments/hello-world.yaml
    git commit -m "Add hello-world deployment"
    git push
    ```

    The node polls for changes every 5 seconds. Within a few seconds of your push, it pulls the new commit, starts the container, and begins health-checking it.
  </Step>

  <Step title="(Optional) Expose the container with a Service">
    To route HTTP/HTTPS traffic to your Deployment through the built-in Caddy ingress, create `services/hello-world.yaml`:

    ```yaml theme={null}
    apiVersion: run.orcra.dev/v0alpha
    kind: Service
    metadata:
      name: hello-world
    spec:
      deployment: hello-world
      ingress:
        domain:
          default: hello-world.example.com
        ssl: true
    ```

    Point `hello-world.example.com` at your node's IP address, then commit and push. Caddy provisions a TLS certificate automatically via ACME on the first request.

    ```bash theme={null}
    git add services/hello-world.yaml
    git commit -m "Expose hello-world via ingress"
    git push
    ```

    <Info>
      Set `ssl: true` only after your DNS record is live and propagated. Caddy performs an ACME HTTP-01 challenge on port 80 to provision the certificate.
    </Info>
  </Step>
</Steps>

## What's next

<CardGroup cols={2}>
  <Card title="How it works" icon="circle-info" href="/concepts/how-it-works">
    Understand the pull-based reconciliation loop in depth.
  </Card>

  <Card title="Node configuration" icon="server" href="/configuration/node">
    All Node manifest fields: SSH, Git, poll interval, data directory.
  </Card>

  <Card title="Deployment configuration" icon="box" href="/configuration/deployment">
    Ports, volumes, environment variables, and health checks.
  </Card>

  <Card title="SSL and ingress" icon="shield-halved" href="/guides/ssl-and-ingress">
    Configure custom domains and automatic TLS for your services.
  </Card>
</CardGroup>