Builds and commands
Configure build, pre-deploy, and start commands and understand caching and build minutes.
Openstead builds repository code in an isolated build environment, then deploys the resulting files or container artifact. Your laptop's installed packages and local uncommitted files are not part of that build.
Use the correct command for each phase
| Setting | Purpose | Examples |
|---|---|---|
| Build command | Compile assets or application output after the builder prepares the project | npm run build, python manage.py collectstatic --noinput |
| Pre-deploy command | Run a one-time release task before starting the new application release | python manage.py migrate --noinput, php artisan migrate --force |
| Start command | Run the application process, worker, or scheduled command | npm run start, gunicorn config.wsgi:application --bind 0.0.0.0:$PORT |
Leave a Railpack command empty to use its detected behavior. An explicit build command replaces the detected build command; make sure it performs every required application build step. A Dockerfile defines its own build instructions, so use its RUN steps rather than expecting the Railpack build-command field to rewrite the Dockerfile.
Keep builds reproducible
- Commit dependency lockfiles such as
package-lock.json,pnpm-lock.yaml,poetry.lock,uv.lock,Gemfile.lock, orcomposer.lock, as appropriate for your toolchain. - Declare the language version in your project's supported version file or manifest.
- Avoid relying on packages installed globally on your development machine.
- Keep secret
.envfiles, local databases, and generated dependency folders out of Git. - Test the production build locally before deploying.
The build environment should not depend on reaching a private runtime database. Run migrations in the pre-deploy phase, which can access the service's permitted private network.
Run a pre-deploy command
Pre-deploy commands require a paid instance. They run with the new deployment's image and secret environment before the new release is activated. A nonzero exit code fails the deployment and preserves the previous release.
The pre-deploy phase runs in a separate execution container. It does not mount the application's persistent disk, and its filesystem changes do not become part of the application image. Build assets during the build phase, not during pre-deploy.
Pre-deploy execution is limited to 30 minutes, or a shorter configured execution timeout. Keep schema migrations backward compatible while the previous release is serving traffic. Pre-deploy commands can run again during a rollback, so they must also be safe to repeat.
Caching and artifact reuse
Openstead maintains a private build cache for each service. Changes to the source, build settings, secrets, or builder can affect reuse. If the same service, commit, and build inputs already produced a usable immutable artifact, Openstead can reuse that artifact without running a new build. Pre-deploy tasks still run when configured.
The public API's clear-cache service action requests a fresh build. Use it to investigate a cache-related failure, not as a routine requirement for every deployment. A normal redeployment can reuse a valid artifact.
Build minutes
Building and pre-deploy execution consume build minutes. Cloning, preparing infrastructure, pulling a release, and runtime health checks do not count as build execution. Workspace Billing shows included and purchased allowance.
When build minutes run out, queued builds wait and active build execution can stop. The previous healthy release stays online. Purchase additional minutes or wait for the monthly allowance to reset; retry a build that already stopped. See Billing.
Diagnose a build failure
Read the first meaningful error in the build log. Later messages often just report the nonzero exit code. Check the application root, lockfile, language version, required variables, and whether a dependency needs system libraries. Use a Dockerfile for custom operating-system packages or a toolchain the automatic builder cannot prepare.