Apps

An App is an application deployed to a cluster through Deckrun.

It can be written in any language and framework that can be built into a Docker image, such as PHP, Node.js, Python, Go, Ruby, etc.

The app's name is unique and acts as a global identifier within your account.

Initializing an App

The first step before deploying an application is to create it in Deckrun. To do this, run the deck init command from the root directory of your project:

deck init

This command will guide you through the following steps:

1. Cluster Selection: You will be prompted to choose the cluster where the application will be deployed.
2. Application Name: You must choose a unique name for your application.

Deckrun will then analyze your project to determine the application type and generate a suitable Dockerfile for building the application's image. If Deckrun cannot detect the language or framework, you will have the option to provide your own Dockerfile.

Finally, a deckrun.toml configuration file will be created in your project's root directory. This file is the blueprint for your application and contains the necessary information for deployment. You should review this file and customize it to fit your needs.

If you already have a deckrun.toml file from another project, you can use the --load-existing-config flag to use it as a base configuration:

deck init --load-existing-config

Deployment

To deploy your application, run the deck deploy command from the root directory of your project:

deck deploy

This command performs the following actions:

1. Builds the Docker image: Using the Dockerfile in your project.
2. Pushes the image to the registry: The image is pushed to your provider's container registry.
3. Deploys the image to the cluster: The new version of your application is deployed to the cluster according to the configuration in your deckrun.toml file.
4. Waits for the application to be ready: The command will wait until the new version of your application is successfully deployed and ready to receive traffic.

By default, deck deploy uses the deckrun.toml file in the current directory. You can specify a different configuration file using the -c or --config flag. This is useful for managing multiple environments, such as staging and production:

deck deploy -c deckrun-staging.toml

Release history

Every deployment creates a new release. You can view your deployment history to see what was deployed, when, and its status:

deck releases

This provides an audit trail of all changes to your application, showing:

• Release number
• Deployment timestamp
• Status (deploying, deployed, error)

Release history helps you track changes over time and understand what version is currently running.

Resource usage

To see how much CPU and memory your application is actually using, run:

deck apps resources

This shows real-time usage for every running pod, grouped by process, alongside the configured requests and limits:

Process: web (size: small)
  Autoscaling: 1–5 replicas (target: CPU 70%)
  POD                CPU USAGE  CPU REQ   CPU LIM   MEM USAGE  MEM REQ   MEM LIM
  web-abc123-x7k2p   180m       1000m     1000m     128Mi      1Gi       1Gi
  web-abc123-r9f3q   210m       1000m     1000m     145Mi      1Gi       1Gi

Process: worker (custom resources)
  POD                CPU USAGE  CPU REQ   CPU LIM   MEM USAGE  MEM REQ   MEM LIM
  worker-def456-m2n  95m        500m      1000m     64Mi       256Mi     512Mi

• CPU USAGE / MEM USAGE: What each pod is actually consuming right now
• CPU REQ / MEM REQ: The guaranteed resources requested in your configuration
• CPU LIM / MEM LIM: The maximum resources the pod is allowed to use

Processes with no size or resources configured still show live usage, but the request/limit columns display -.

By default, the command reads the app name from your deckrun.toml. Use --app to specify a different app or --config to point to a different config file:

deck apps resources --app myapp
deck apps resources --config deckrun-staging.toml

This is particularly useful when sizing your processes — comparing actual usage against your configured requests helps you avoid over-provisioning or under-provisioning.

Configuration file

The deckrun.toml file determines how the application should be deployed and run in the cluster.

Example of a deckrun.toml file:

# deckrun.toml file automatically generated on Sat Mar  1 12:43:05 CET 2025

app = 'laravel'

[env]
APP_DEBUG = 'false'
APP_ENV = 'production'
DB_CONNECTION = 'mysql'
LOG_CHANNEL = 'stderr'
LOG_LEVEL = 'info'

[deploy]
[deploy.pre]
command = 'php artisan migrate --force'

[[processes]]
name = 'app'

[processes.http]
internal_port = 8080

[[processes]]
name = 'worker'
command = 'php artisan queue:work'

[[cronjobs]]
name = 'scheduler'
schedule = '* * * * *'
command = 'php artisan schedule:run'

This example shows a simple application with a web process, a worker process, and a cron job. You can learn more about configuring processes and cronjobs in their respective documentation pages.

Best Practices

• Use clear and unique names: We recommend using a naming convention such as project-environment (e.g., myapi-prd, myapi-stg). This helps to avoid confusion and makes it easier to manage applications in the UI and CLI.

• Version control your deckrun.toml: We recommend committing the deckrun.toml file to your version control system. This ensures that your deployment configuration is tracked along with your code, making it easier to collaborate and roll back changes if needed.

• Add custom domains for production: When you are ready to go live, add a custom domain to your application.

• Use secrets for sensitive data: Use secrets to manage API keys, tokens, or credentials. Secrets are injected as environment variables, but they are stored securely and are not checked into your deckrun.toml file.

• Keep your Docker images small: Smaller images lead to faster deployments and reduced storage costs. You can optimize your Docker images by using a .dockerignore file to exclude unnecessary files, and by using multi-stage builds to create smaller final images.