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

# Enable HTTPS ingress with automatic SSL in orun

> How to create a Service manifest to expose a Deployment on a custom domain with automatic TLS certificate provisioning via the embedded Caddy server.

orun ships an embedded [Caddy](https://caddyserver.com/) server that handles HTTP/HTTPS routing and TLS certificate provisioning automatically. You do not need to install or configure Nginx, Traefik, or any other reverse proxy — creating a `Service` manifest is all it takes to put a deployment behind a domain with valid SSL.

## Prerequisites

* A Deployment already running on the node (see [Deploy a container application with Orcra Run](/guides/deploy-your-first-app))
* A domain name with a DNS `A` record pointing to the node's public IP address
* Ports `80` and `443` open on the node's firewall

<Warning>
  Point your DNS record at the node **before** setting `ssl: true`. Caddy provisions certificates via Let's Encrypt HTTP-01 challenges on port 80. If DNS does not resolve to the node at that moment, certificate provisioning fails and Caddy retries with backoff.
</Warning>

<Steps>
  <Step title="Create the Service manifest">
    Create the file `services/hello-world.yaml` in your manifest repository:

    ```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
    ```

    **Key fields:**

    | Field                         | Required | Default | Description                                      |
    | ----------------------------- | -------- | ------- | ------------------------------------------------ |
    | `spec.deployment`             | Yes      | —       | Name of the Deployment to route traffic to       |
    | `spec.ingress.domain.default` | Yes      | —       | Primary domain for this service                  |
    | `spec.ingress.ssl`            | No       | `false` | Enable automatic TLS via Caddy and Let's Encrypt |
  </Step>

  <Step title="Commit and push">
    ```bash theme={null}
    git add services/hello-world.yaml
    git commit -m "Add hello-world service with SSL"
    git push
    ```
  </Step>

  <Step title="Wait for the node to pick up the change">
    Within one poll interval (default `5s`), the node reads the new Service manifest and reconfigures Caddy. Caddy begins the Let's Encrypt ACME flow immediately, which typically completes within a few seconds when DNS is already propagated.
  </Step>

  <Step title="Verify HTTPS is working">
    Open a browser or run:

    ```bash theme={null}
    curl https://hello-world.example.com
    ```

    You should receive a valid response with a trusted Let's Encrypt certificate. Caddy handles certificate renewal automatically before expiry.
  </Step>

  <Step title="Use per-environment domains (optional)">
    If you use Git branches as environments, you can configure a domain template that includes the branch name:

    ```yaml theme={null}
    spec:
      deployment: hello-world
      ingress:
        domain:
          default: hello-world.example.com
          environment: hello-world.$ENV.example.com
        ssl: true
    ```

    The `$ENV` placeholder is replaced at runtime with the name of the branch the node is tracking. For example, a node on the `staging` branch serves `hello-world.staging.example.com`, while a node on `main` falls back to `hello-world.example.com`.
  </Step>
</Steps>

<Note>
  The embedded Caddy HTTP and HTTPS ports default to `80` and `443`. You can override them with the `--caddy-http-port` and `--caddy-https-port` flags passed to `orun start`. This is useful when testing locally or when another process holds the standard ports.
</Note>

<CardGroup cols={2}>
  <Card title="Deploy your first app" icon="rocket" href="/guides/deploy-your-first-app">
    Create a Deployment manifest that orun pulls and runs automatically.
  </Card>

  <Card title="Monitor containers and view logs" icon="chart-bar" href="/guides/monitoring-and-logs">
    Inspect orun agent logs and query the status API for deployment health.
  </Card>
</CardGroup>