Processes

How your application splits its workload across containers.

An application on Nodion can run more than one kind of container at the same time. Each kind is called a process. A typical web app has a web process that handles HTTP traffic and a worker process that runs background jobs. They share the same code, but each one has its own command, its own scaling, and optionally its own ports, volumes and environment variables.

Processes are first-class objects in Nodion. You define and edit them in the dashboard regardless of how your code is built. The build artifact (a Docker image, a buildpack-built image, or a prebuilt image) is one thing. How you run it is another.

Two kinds of processes

• Long-running. A container that boots up, listens for traffic or background work, and stays alive. Scales horizontally. Think web, worker, scheduler.
• Run. A one-shot stage that fires at a specific moment, finishes, and exits. Used for database migrations, cache warm-ups, seed scripts. Think release, update.

How processes are defined

There are three ways a process gets into your application. They all end up in the same place: the Processes tab in your dashboard.

1. Manually from the dashboard

Open the Processes tab and click + Add Process. Pick the type (long-running or run), give it a name, set a start command, choose an instance type, and define ports or a run policy. This works for every application, no matter how your code is built.

For applications built from a Dockerfile, the Start command field overrides the Docker CMD at container start. That's how you run multiple processes from a single image: one image, many run-configurations.

# Dockerfile (single image)
FROM ruby:3.3
COPY . /app
WORKDIR /app
RUN bundle install
CMD ["bundle", "exec", "puma"]Dockerfile

With the Dockerfile above, you can define two processes in the dashboard:

• web with no start command override. Runs bundle exec puma from the Docker CMD.
• worker with start command bundle exec sidekiq. Same image, different command.

2. Automatically from a Procfile (buildpack apps)

If your repository contains a Procfile at the root and you build with buildpacks, Nodion reads it during the build and turns each entry into a process. You don't need to click anything together. Your code defines what runs.

web: bundle exec puma
worker: bundle exec sidekiq
release: bundle exec rails db:migrateProcfile

The example above declares two long-running processes (web and worker) and one run (release). On the next deploy you'll see them appear under the Processes tab.

3. Automatically from a Preset

Some frameworks ship with a preset that defines an update run for first-time setup, things like schema bootstrap or seed data. Presets behave like a Procfile entry, just from the framework metadata rather than your repository.

The web process and $PORT

If you have a process named web (manually or via Procfile), Nodion treats it specially. A default HTTP port and subdomain are configured automatically, and the container is booted with a PORT environment variable that tells your application which port to bind on. That way you don't need to hard-code anything:

const port = process.env.PORT || 3000;
app.listen(port);Node.js

For other process names, ports are optional. If you want them reachable from the public internet, add at least one port in the dashboard. Without ports, the process runs as background work only.

Settings on a long-running process

• Start command. What the container runs. Overrides Docker CMD. Optional for buildpack apps with a matching Procfile entry.
• Instance count. How many copies of this process should run in parallel. Set to 0 to keep the process configured but not deployed.
• Instance type. The hardware tier (CPU, memory) for each container. Different processes can run on different sizes, so a small worker doesn't need to share resources with a beefy web tier.
• Ports. Which ports the container exposes. A process becomes reachable from outside as soon as it has at least one port. Without ports it's purely background work.
• Volumes. Persistent storage attached to this process. See Volumes for details.
• Environment variables. Process-level variables that override the application-level ones with the same key. See Environment Variables for details.

Settings on a run

• Start command. The one-shot command to execute. Required.
• Run policy. When the run fires:
  • Every deploy. Runs on each successful build. The default for release:.
  • First deploy only. Runs once when the application is first set up, then never again automatically.
  • Manual. Only runs when you trigger it from the dashboard or API.
• Timeout. How long the run is allowed to take before being killed.
• Instance type. Runs always execute on a single instance with the selected hardware tier.
• Volumes and environment variables. Same as long-running processes, but usually only set if the run needs them.

The most common run is release. It runs before your new code goes live, on every deploy. If it fails, the deploy is rolled back and your old version keeps serving traffic.

You'll find the result of the latest run on each run's card in the dashboard, including its exit status and a link to the logs.

Scaling and editing

Open the Processes tab on your application. Each process gets its own card with quick actions for scaling, viewing instances, editing settings, attaching volumes and managing environment variables. Changes take effect on your next deploy or scale event.

Drift: when your Procfile and your dashboard disagree

If your processes are discovered from a Procfile or preset, Nodion tracks them on every deploy. When an entry disappears from the source (say, you removed worker: from your Procfile), the process is flagged as drifted. Nodion doesn't stop it automatically. It keeps running with its current settings, and the next time you open the Processes tab you'll see a banner asking what you want to do.

You have two choices:

• Keep as manual. The process keeps running and becomes a manual process. Future Procfile changes won't affect it. Use this when you removed an entry from the Procfile by accident, or when you want to take direct ownership of how this process runs.
• Stop and orphan. The process is marked as orphaned and stops running on the next deploy. Its configuration is preserved, so if you re-add the entry to your Procfile later it picks up where it left off.

Manually-created processes are never affected by Procfile changes. They're yours, and Nodion doesn't touch them.

Strict mode (GitOps)

The behaviour above is the default. We call it lenient mode. If you'd rather have a pure GitOps workflow where the Procfile (or preset) is the single source of truth, switch to strict mode in the Procfile sync mode card on the Processes tab.

In strict mode:

• Entries that disappear from your Procfile are auto-orphaned on the next deploy. No banner, no confirmation.
• If you manually create a process and later add the same name to your Procfile, the Procfile entry takes ownership. Your manual configuration is replaced by what's in code.
• You can still add processes from the dashboard, but they're effectively floating until the next reconcile.

Switching modes only affects future deploys. Existing drift markers stay until the next deploy resolves them.

What changes on each deploy

• A new entry in your Procfile becomes a new process. Long-running processes start at 0 instances so you can configure them before they go live. The web process is the exception and is set up immediately.
• An entry that was already there keeps its existing settings. Your scaling config, port assignments, volumes and environment variables aren't touched.
• An entry that disappeared from the Procfile is flagged as drifted (see above). Nothing stops automatically.
• If you delete a Procfile-sourced process from the dashboard, it stays deleted. If you re-add the same name to your Procfile and push, it comes back with the previous configuration.
• Manually-created processes are unaffected by Procfile reconciliation.