Docs / Apps

Build settings

4 minute read

SimpliCloud detects how to build most apps on its own. When it guesses wrong, set the build and run commands, the port and the source folder yourself.

1. How detection works

On each deploy SimpliCloud looks at the root of the repository and picks a builder:

Found	Builder	Default commands
`Dockerfile`	Docker	Builds and runs the Dockerfile as it is
`package.json`	Node.js	`npm ci`, `npm run build`, `npm start`
`requirements.txt` or `pyproject.toml`	Python	`pip install`, then the run command you set
`composer.json`	PHP	`composer install`, served by PHP-FPM

A Dockerfile always wins. Delete it or set the builder by hand if you want the Node.js or Python builder instead.

2. Change the settings

Open the app, go to Settings → Source and runtime and change any of these, then click Save and redeploy.

Repository and Branch: what to build.
Source directory: for monorepos, the folder that holds the app, like apps/web.
Build command: runs once per deploy, like npm run build.
Run command: starts the app, like node server.js or gunicorn app:app.
Port: where the app listens. Defaults to 3000 for Next.js and 8080 for everything else.

3. Listen on $PORT

SimpliCloud sets PORT for you. Read it rather than hard-coding a port, and listen on 0.0.0.0, not localhost:

server.js

const port = process.env.PORT || 8080;
app.listen(port, "0.0.0.0", () => console.log("listening on " + port));

The deploy waits for the app to answer on that port. If it never does, the deploy fails and the old version keeps running.

4. Pin the runtime version

Set the Node.js version in package.json so a dependency that needs a newer Node doesn't break the build:

package.json

{
  "engines": { "node": ">=22" }
}

For Python, add a .python-version file with a version like 3.12.

5. Set it from code

simplicloud apps update storefront \
  --source-dir apps/web \
  --build-command "npm run build" \
  --run-command "npm start" \
  --port 3000

Was this page helpful?