Skip to content

Linux application runtime

Overview

The Linux runtime deploys any application: you choose the tools it needs, and the commands that build and start it. Mise installs these tools, such as Crystal, Dart, Gleam, Nim, Zig, or Deno, then Clever Cloud runs your commands.

Use it for a language without a dedicated runtime, for a self-hosted software, or to control each step of your deployment.

Create your Linux application

To create a new Linux application, use the Clever Cloud Console or Clever Tools:

clever create --type linux

Configure your Linux application

Mandatory needs

A Linux application needs:

  • A start command, set in CC_RUN_COMMAND, in a run task of Mise, or in a run target of a Makefile
  • A web server listening on 0.0.0.0, on the port in PORT

A build command is optional, and a Clever Task doesn’t need a web server.

Mise reads a mise.toml file at the root of your project. Its [tools] section lists the tools to install and their versions, and its [tasks] section names the commands of your project. For instance, a Crystal web server, compiled into a server executable:

mise.toml
[tools]
crystal = "1.22"

[tasks.build]
run = "crystal build --release main.cr -o server"

[tasks.run]
run = "./server"
main.cr
require "http/server"

port = ENV.fetch("PORT", "8080").to_i

server = HTTP::Server.new do |context|
  context.response.print "Hello from Linux on Clever Cloud"
end

server.bind_tcp("0.0.0.0", port)
server.listen

To try it locally, run mise trust and mise install, then mise run build and mise run run, and open http://localhost:8080.

Build and run commands

Clever Cloud looks for the build command and the start command separately, in this order:

  1. CC_BUILD_COMMAND and CC_RUN_COMMAND
  2. The build and run tasks of Mise, in mise.toml or in file tasks
  3. The build: and run: targets of a Makefile

Each source only fills in the commands that a previous one doesn’t define. For instance, you can set CC_BUILD_COMMAND only, and let a run task of Mise or a run target of a Makefile provide the start command.

Clever Cloud looks for these files at the root of your project, or of the CC_APP_FOLDER folder, before the pre-build hook: a hook can’t create them. It runs the Mise tasks from the folder of mise.toml, which CC_MISE_FILE_PATH can move. For the Makefile, it uses the first file it finds among:

  • The file set in CC_MAKEFILE
  • GNUmakefile, Makefile, then makefile

It checks each target with make --dry-run, and ignores the ones that fail. Without a start command, the deployment fails with You must define a CC_RUN_COMMAND or a 'run' task with Makefile or Mise.

Build phase

Before an instance starts, Mise installs the tools of mise.toml. On a new build, Clever Cloud then runs the pre-build hook, the build command, and the post-build hook. CC_BUILD_COMMAND and the Makefile targets run from the root of your project, or from the folder set in CC_APP_FOLDER.

Start command

A run target of a Makefile runs from the root of your project, or from the folder set in CC_APP_FOLDER. A Mise task runs from the folder of mise.toml. CC_RUN_COMMAND runs from the root of the repository, through a shell: it reads variables such as $PORT.

Caches

After a successful build of an application, Clever Cloud keeps a build cache of the commit, with your whole repository. Restarting the application without a code change reuses it and skips the build. To build again from scratch, restart without the cache (rebuild):

clever restart --without-cache

Mise installs the tools again on each restart, even from the cache. With CC_CACHE_DEPENDENCIES=true, Clever Cloud also keeps the files Mise downloads between commits, in the ~/.cache/mise folder.

Linux applications as Clever Tasks

A Linux application can run as a Clever Task, such as a job or a migration: Clever Cloud builds it, then runs CC_RUN_COMMAND.

Configure Tasks from the Information panel in the Console or with Clever Tools, here for a report task you define in mise.toml:

clever create --type linux --task "mise run report"
clever deploy # or clever restart if there is no code change

Expand your toolbox with Mise package manager

Install tools with Mise package manager

Mise installs tools and their versions on every Clever Cloud runtime. Add a mise.toml file at the root of your project: Clever Cloud installs the tools it lists before the build phase. It can also define environment variables and tasks.

To place this file in another folder, set its path in CC_MISE_FILE_PATH, such as config/mise.toml: Mise runs from this folder.

To disable Mise, set CC_DISABLE_MISE=true: Clever Cloud then installs no tool from mise.toml, and the Linux runtime ignores Mise tasks.

Go Further

Last updated on