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

> ## Agent Instructions
> Treat Stackdome as an application-delivery platform for coding agents and developers, not as a Kubernetes dashboard.
> Prefer the Stackdome agent plugin as the user entry point and the stackdome CLI as the execution interface.
> Route agents who need the maintained deploy skill to npx skills add stackdome/skills and the complete operational workflow to /guides/ai-agents.
> Verify commands and flags with stackdome --help. Run stackdome init before authoring stackfile.yaml and stackdome validate before deploying.
> Use -o json for automation and verify documented terminal states before claiming success.
> Never request a user's account password. Use API-token authentication.
> During alpha, Stackdome Cloud is ephemeral and capacity-limited, and each organization can connect one cluster.
> Do not expose Kubernetes as a user concern unless the task is self-hosting or infrastructure architecture.

# Deploy from git

> Connect a git provider and build your repository into a running resource.

## Outcome

Deploy the public [Stackdome demo repository](https://github.com/Stackdome/stackdome-demo) as a three-resource stack. Stackdome builds its web application and worker from separate repository contexts, runs Redis from a published image, provisions persistent Redis storage, and waits until the release is healthy. The web resource produces a public URL you can return to the user.

## Prerequisites

* A local clone of `https://github.com/Stackdome/stackdome-demo.git`. The example application is under `hello-stack`.
* The URL of Stackdome Cloud or a self-hosted installation, plus an API token. See [authentication and API tokens](/reference/authentication).
* Stackdome Cloud supplies the registry used for git builds. On self-hosted Stackdome, git builds require [connected compute with an image registry](/self-host/connect-compute).
* For a private repository, a git provider already connected to the organization. The current public CLI cannot create or manage git-provider credentials; use the dashboard flow below or the API before deploying.
* For the GitHub App flow on a self-hosted installation, an externally reachable `SERVER_EXTERNAL_URL` and a GitHub account allowed to install the app for the repository owner.

## Agent prompt

```text theme={null}
Clone https://github.com/Stackdome/stackdome-demo.git and deploy its hello-stack application to Stackdome. Use the repository's Compose file as an architectural reference for creating the Stackfile, and cross-check it against the Dockerfiles and README. Run stackdome init beside hello-stack/docker-compose.yml only as experimental scaffolding, replace local build paths with the repository URL and repository-root contexts, validate every edit, authenticate only with an API token, deploy with stackdome deploy --wait -o json, retain the returned release ID, verify that the converged release ID matches it and converged health is ok, and return the web URL.
```

## Agent actions

<Steps>
  <Step title="Inspect the repository">
    Use `hello-stack/docker-compose.yml` as the topology reference, then cross-check `hello-stack/README.md` and both Dockerfiles. Create one Stackfile resource for each service and carry over only behavior supported by the Stackfile schema. The repository declares `web` on port `3000`, a stateless `worker`, Redis on port `6379`, and persistent Redis data under `/data`.
  </Step>

  <Step title="Initialize the Stackfile">
    Run `stackdome init --name hello-stack` from the repository's `hello-stack` directory. Its experimental converter creates a draft from `docker-compose.yml` and warns that the two local builds need a git repository. Treat the Compose file—not the generated draft—as the source of architectural hints.
  </Step>

  <Step title="Set the git build source">
    Set both build resources to `https://github.com/Stackdome/stackdome-demo.git` on `main`. Use `hello-stack/web` for the web context and `hello-stack/worker` for the worker context because build paths are resolved from the cloned repository root.
  </Step>

  <Step title="Validate and authenticate">
    Run `stackdome validate`, then authenticate with `stackdome login --url https://<your-stackdome-host> --token <api-token>` and confirm the active scope with `stackdome whoami -o json`.
  </Step>

  <Step title="Deploy and verify">
    Run `stackdome deploy --wait -o json`, retain its non-empty `release.id` as the deployed release ID, then run `stackdome status -o json`. For a public service, run `stackdome open -o json` and return an entry from `urls`.
  </Step>
</Steps>

Pushing a commit does not deploy an ordinary stack automatically. Run the deploy command again to build the current branch, tag, or commit. Preview environments are the exception described in [preview environments](/guides/preview-environments).

## Success criteria

* `stackdome validate` exits successfully for the generated `stackfile.yaml`.
* `stackdome deploy --wait -o json` exits successfully, returns a non-empty `release.id` that is retained as the deployed release ID, and returns `release.state` as `Released`.
* `stackdome status -o json` returns `converged_release.id` equal to the deployed release ID, `converged_release.state` as `Released`, and `converged_release.health` as `ok`.
* A public service returns at least one entry in the `urls` array from `stackdome open -o json`.
* The Stackfile records both demo build contexts, web port `3000`, Redis port `6379`, Redis dependencies, and the persistent `/data` mount found in the repository.

## CLI workflow

Clone the demo and run the initializer beside its Compose file:

```bash theme={null}
git clone https://github.com/Stackdome/stackdome-demo.git
cd stackdome-demo/hello-stack
stackdome init --name hello-stack
```

The initializer discovers all three services and the Redis volume. It cannot turn local Compose build paths into a remote source automatically, so complete the generated file with the repository URL and repository-root contexts:

<Warning>
  Docker Compose conversion is experimental. Use Compose to understand the application and create the Stackfile; a converted Stackfile is only a draft and usually needs manual work for build-based services. Compose paths such as `./web` are relative to the local Compose file; Stackdome needs a Git repository URL and a context relative to the root of the cloned repository. Review every converted resource and require `stackdome validate` to pass before deployment.
</Warning>

```yaml theme={null}
name: hello-stack

resources:
  web:
    build:
      repo: https://github.com/Stackdome/stackdome-demo.git
      branch: main
      context: hello-stack/web
    ports:
      - name: http
        port: 3000
        protocol: HTTP
        public: true
    env:
      CELEBRATION: confetti
      HAT: party
      HEADLINE: Your stack is now live.
      PUBLIC_URL: "{{ self.public_url }}"
      REDIS_URL: "redis://{{ redis.host }}:6379"
    depends_on:
      - redis

  worker:
    build:
      repo: https://github.com/Stackdome/stackdome-demo.git
      branch: main
      context: hello-stack/worker
    env:
      CELEBRATION: confetti
      REDIS_URL: "redis://{{ redis.host }}:6379"
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    command:
      - redis-server
      - --appendonly
      - "yes"
    ports:
      - name: redis
        port: 6379
        protocol: TCP
        public: false
    volumes:
      - name: redis
        path: /data
    workload_type: StatefulService

volumes:
  redis:
    size: 1Gi
    access_mode: ReadWriteOnce
```

The two build contexts are relative to the repository root, not to the directory where you ran the CLI. `{{ redis.host }}` creates the resource connection and supplies the destination hostname to both Node.js processes. Omit `branch` and `tag` to let the server resolve the repository's default branch. To pin a commit, set `commit` together with the branch or tag from which Stackdome can fetch it. See the [Stackfile guide](/guides/stackfile) for the Compose conversion details and the [Stackfile reference](/reference/stackfile) for every field.

Validate before authentication or deployment:

```bash theme={null}
stackdome validate
stackdome login --url https://<your-stackdome-host> --token <api-token>
stackdome whoami -o json
stackdome deploy --wait -o json
stackdome status -o json
stackdome open -o json
```

For a private repository, configure its provider through the dashboard or API first. The public CLI has no git-provider management command. Do not put provider tokens in `stackfile.yaml`.

## Troubleshooting

Start with structured CLI output. Use the release ID returned by `stackdome deploy -o json` and the build ID returned by `stackdome build list`:

```bash theme={null}
stackdome build list
stackdome build info <build-id>
stackdome build logs <build-id>
stackdome release events <release-id> --follow
stackdome status -o json
stackdome logs <resource> --tail 100
```

Check the build definition before retrying: a private repository needs a configured provider, the selected revision must exist, and `dockerfile` is relative to `context`. On self-hosted Stackdome, also confirm that connected compute has an image registry. A failed `stackdome deploy --wait -o json` is not a successful deployment even if the stack document was applied.

## Related tasks

<CardGroup cols={2}>
  <Card title="Deploy with a coding agent" icon="sparkles" href="/guides/ai-agents">
    Follow the complete agent operating contract, verification rules, and failure routes.
  </Card>

  <Card title="Stackfile reference" icon="file-code" href="/reference/stackfile">
    Configure build revisions, contexts, ports, environment values, dependencies, and storage.
  </Card>

  <Card title="Deploy from an image" icon="container" href="/guides/deploy-from-image">
    Run an image that was already built and published elsewhere.
  </Card>

  <Card title="Preview environments" icon="git-pull-request" href="/guides/preview-environments">
    Build isolated releases for supported pull-request events.
  </Card>
</CardGroup>