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

# Build a multi-service application

> Create an application, add public and private services from one repo or many, and let each service deploy independently while sharing one private network.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Run a frontend, APIs, workers, and databases as one application where only the services you choose are exposed to the internet.

## Prerequisites

* A StackShift account
* A GitHub repository (monorepo or one repo per service)

## Workflow

<Steps>
  <Step>
    Create an application from Dashboard -> Applications. The name sets the internal domain every service shares.
  </Step>

  <Step>
    Add each service with its repository, root directory, port, and type (web service, background worker, or scheduled job).
  </Step>

  <Step>
    Mark services public or private. Public services get a URL on the internet; private services are only reachable by their siblings.
  </Step>

  <Step>
    Attach managed databases to the application so services can connect to them.
  </Step>

  <Step>
    Deploy services individually — a push to a monorepo only rebuilds the services whose directories changed.
  </Step>
</Steps>

## What an application gives you

* One private network per application — services in different applications cannot reach each other, even by IP.
* A stable internal hostname per service that survives redeploys and always points at healthy instances.
* Independent builds and deploys per service, each with its own repository, branch, root directory, logs, and environment.
* A dependency map in the dashboard showing which services talk to each other and why.

## Import everything from one file

Instead of adding services one by one, paste a stackshift.yaml in the Import tab. Preview first to see exactly what would be created.

```yaml theme={null}
application: ecommerce
services:
  frontend:
    type: web
    visibility: public
    rootDirectory: apps/frontend
    port: 3000
    bindings:
      - service: api
        env: API_URL
  api:
    type: web
    visibility: public
    rootDirectory: apps/api
    port: 8080
  worker:
    type: worker
    rootDirectory: workers/notify
    bindings:
      - service: api
        env: API_URL
```

## Expected result

<Check>
  Every service has a stable internal hostname like api.myapp-1a2b3c4d.stackshift.internal, and only the services you marked public answer on the internet.
</Check>

## Common failures

<Warning>
  * service has no port: internal URLs need a port — set one on the service and redeploy.
  * two services share an internal name: service names must be unique inside an application.
  * a private service is unreachable from another app: this is by design — applications are isolated from each other.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Private networking and connections" href="/applications/private-networking-and-bindings">
    Connect one service to another so StackShift injects the internal URL as an environment variable — no IPs or hostnames to copy, and private services never touch the public internet.
  </Card>

  <Card title="Deploy from GitHub" href="/projects/deploy-from-github">
    Use the repository-backed project flow when you want StackShift to detect the app, build from source, and let you override runtime behavior before the first deploy.
  </Card>

  <Card title="Worker and background processes" href="/projects/worker-processes">
    Run a project as a background process type (worker, queue, scheduler, reverb) instead of a public web service.
  </Card>
</CardGroup>