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

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.