Concepts

Organizations

An organization is the top-level container for everything in Podway. It maps to your team or company. All projects, apps, billing, and members belong to an organization.

Projects

Projects group related apps together. For example, you might have a my-saas project containing a backend app, a frontend app, and a worker app.

Apps

An app represents a single deployable service. Each app:

• Has one GitHub repository connected to it
• Can have multiple environments (production, staging, etc.)
• Builds Docker images from your repository
• Gets its own subdomain on deployment

Environments

Environments let you run multiple versions of the same app — for example, production and staging. Each environment:

• Has its own configuration (environment variables, resources)
• Has its own deployments and build history
• Gets its own default domain ({app-slug}-{env-name}.podway.dev)
• Can have auto-deploy enabled for specific branches

Builds

A build compiles your source code into a Docker image and pushes it to GHCR. Builds are triggered:

• Manually — from the Builds tab with a specific commit SHA
• Automatically — via GitHub push webhooks when auto-deploy is enabled

Build logs stream in real time so you can see exactly what’s happening.

Deployments

A deployment takes a successfully built image and runs it on Kubernetes. Each deployment:

• Creates or updates a Kubernetes Deployment in your app’s namespace
• Sets up TLS automatically via cert-manager
• Creates a DNS record for your default domain
• Can be rolled back to a previous deployment

Default domains

Every environment gets a default domain automatically on first deployment:

https://{app-slug}-{env-name}.podway.dev

For example, an app named my-api in a production environment gets:

https://my-api-production.podway.dev

Custom domains

You can add your own domain to any environment. Podway handles TLS automatically via Let’s Encrypt. See Custom Domains for setup instructions.