Deploy an App

This page covers the full deploy path: creating an app, pushing code, and the build system that takes it from there.

Create an app

watasu create my-app

This creates the app, returns a managed URL (https://my-app.watasu.app), and adds a Git remote named watasu pointing at git.watasu.io.

Useful flags:

Flag	What it does
`--addons postgresql,valkey:hobby-1`	Provision and attach add-ons in the same call
`--no-remote`	Skip adding the local Git remote

Apps currently deploy to the eu region. See Regions for the full picture, including where add-on followers can run.

Push your code

git push watasu main

That’s the deploy. Watasu stages the source, builds an image, creates a release, rolls it out, and streams build + release output back to your terminal.

You can push from any branch — Watasu treats the push as the deploy regardless of branch name. (For branch-driven workflows, use GitHub auto-deploy instead.)

How Watasu builds your code

The rule is simple:

Dockerfile present → Watasu builds your Dockerfile directly. You’re in full control of the image.
No Dockerfile → Watasu uses Cloud Native Buildpacks to detect your language and assemble an image.

That’s it. There’s no third detection path and no platform-specific build config to learn.

When to add a Dockerfile

Reach for a Dockerfile when:

your app needs system packages or build tools the standard buildpack stack doesn’t ship
you want bit-for-bit control of the image (compliance, custom base image, security scanning)
you’re deploying a binary built outside Watasu

For most application code in mainstream languages, buildpacks are faster to set up and easier to maintain.

Process types and the Procfile

Watasu reads a Procfile at the root of your repo to discover process types:

web: bundle exec puma -C config/puma.rb
worker: bundle exec sidekiq
release: bundle exec rails db:migrate

Without a Procfile, Watasu can still deploy by inferring a default web process for typical web apps. Add a Procfile as soon as you need:

a worker process for background jobs
multiple public web entrypoints (e.g. web + admin-web + api-web) — each gets its own URL
a private TCP service for microservices (*-tcp) — see Private Networking
a WebRTC or real-time service (*-rtc) — see Real-Time and WebRTC
a release process for migrations or one-time setup

Process names matter — the suffix decides how Watasu routes the process. See Processes and Scaling for the full table, or Core Concepts for the short version.

Release processes

A process named release runs once per deploy, before the new release goes live. It’s the right place for:

database migrations
one-time per-release setup checks
cache priming or invalidation

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

A failing release process aborts the deploy — the new code never rolls out. Keep it fast and idempotent.

Deploying from GitHub

Pushing to the watasu Git remote is the most direct path, but it’s not the only one. You can connect a GitHub repo and let Watasu deploy on every branch push, run pipelines for staged delivery, and spin up a review app for every pull request.

See Connect GitHub and Pipelines and Promotions.

When a deploy goes wrong

Most deploy failures fall into a handful of buckets:

build failed — buildpack didn’t detect the app type, or Dockerfile failed to build
release process failed — usually a migration error or missing config var
app boots but doesn’t bind to its port — listen on 0.0.0.0:$PORT, not 127.0.0.1
app boots and crashes — a missing config var, a failed dependency, an exception during startup

Start with the logs:

watasu logs --app my-app

Then see Troubleshooting → Common Issues for specific symptoms.