Documentation

Guide / Docker deployment

Deploy a Docker app from a Dockerfile

Deploy a Docker app from a Dockerfile in GitHub. This guide uses the public Node.js task board as its example. This sample stores tasks in memory, so a restart restores its three starter tasks. Use the PostgreSQL sample when task data must persist.

Before you start

Create a fork of the sample repository, sign in to Resilis, and connect a GitHub account that can access your fork. The docker-guide branch contains the Dockerfile walkthrough.

Select the source and target

If you already deployed main to Development, add a Staging instance to the same app. Select docker-guide so each environment tracks its own branch. Otherwise, create an app from your fork and select docker-guide with Staging. Set the app root to a single dot (.). The verified target was Resilis Cloud EU; select an available target in your account.

Configure the Dockerfile build

Open Configure and select Advanced build and region settings. Choose Dockerfile. Leave the build and start command overrides empty so Resilis uses the commands in the Dockerfile. The checked-in Dockerfile runs the app as a non-root user.

Advanced app configuration with Dockerfile selected as the build strategy.
The recorded configuration uses the Dockerfile strategy.

Set the app variables

Use Import to add the detected variable names. Import adds names only. Set PORT to 3000 and DEMO_READ_ONLY to false while you test your own editable deployment.

Editable deployment

PORT=3000
DEMO_READ_ONLY=false

Deploy and check the app

Select Deploy Application and wait for the deployment to show Running. Open the live URL and visit /ready. The endpoint reports ready with memory storage. Add a task and move it to Doing to check the board.

Readiness endpoint

/ready
The Docker task board shows Ship the Docker sample in the Doing column.
The task was created and moved during the recorded deployment check.
Transcript: plain-text transcript

Understand restarts and read-only demos

The Dockerfile packages the app but does not make tasks persistent. This sample stores tasks in memory. Restarting or redeploying clears added tasks and restores the three starter tasks. Use the PostgreSQL sample when task data must persist.

For a shared demo, set DEMO_READ_ONLY to true after your edit checks. Turn off Redeploy current image before saving, then choose Save. Open Configuration, choose Build, and select Rebuild. Verify that GET /api/config reports read-only mode and that a write request returns HTTP 403. The shared Docker demo is already read-only.

The Resilis Staging app overview shows the Docker deployment as Running.
The captured Docker deployment uses the docker-guide branch.

Prepare the image inputs and startup command

To deploy a Dockerfile from your own repository, check that the selected app root and Dockerfile path point to the intended files. Review the files copied into the image and the dependency lockfile used during installation. A file that exists on your computer but is absent from the selected repository revision will not be available to the remote build.

Keep credentials out of the Dockerfile and source files. Supply application secrets through the environment settings. Review the image startup instruction and ensure its referenced application files exist in the final image. For this sample, leaving build and start overrides empty preserves the checked-in Dockerfile startup path and its non-root runtime user.

Align container networking and app configuration

The web process must listen on 0.0.0.0 and the port configured for the deployment. Set PORT=3000 for this walkthrough and ensure your own server reads its configured value. A Dockerfile EXPOSE instruction describes a port; it does not start a listener or change the host address. Check the running application when diagnosing an unreachable URL.

The recorded container runs the memory-backed task board. Packaging it as an image does not add a database or preserve records after process replacement. For persistent application data, use the PostgreSQL guide, keep app and database in the same project, environment, and region, and supply the internal DATABASE_URL as a secret.

Update the Docker deployment and inspect logs

When the GitHub webhook and selected-branch deployment trigger are configured, a push to docker-guide can update this Staging instance. A push to main belongs to the separate branch choice used by Development. Confirm the environment before evaluating an update. You can also open Configuration, choose Build, and select Rebuild to request a manual build.

Use build logs to locate missing copied files, dependency installation errors, and failing image instructions. For a lockfile installation failure, commit a matching manifest and lockfile for the package manager invoked by the Dockerfile. For a missing start script, correct the image command or add the intended production script. Check the selected root, Dockerfile path, and committed source before editing the runtime settings. If the image builds but the process exits, use runtime logs to inspect startup and required variables. After a successful update, repeat the live board and /ready checks. App rollback changes the deployment version and cannot restore memory-only tasks.

Docker deployment questions

Does selecting Dockerfile use Railpack defaults? The Dockerfile strategy follows the image build route. In this walkthrough the command overrides stay empty so that the checked-in Dockerfile controls the application startup.

Why can I build the image but not open the app? Check that the process stays running, binds to 0.0.0.0, and listens on the configured port. EXPOSE alone does not make an application accept requests.

Why do writes return HTTP 403? The shared Docker demo is read-only. Check GET /api/config and use DEMO_READ_ONLY=false in your own deployment while testing edits. Rebuild after saving the intended setting.

Will a rebuild keep the task I added? No. This Docker sample stores tasks in memory and restores its starter board when the process restarts. The PostgreSQL example demonstrates persistence across a rebuild.

Choose the walkthrough that matches your build and storage needs. The examples use different branches or repositories; keep the source and environment from the selected guide together.

Deploy it with your AI agent instead

A connected AI agent can deploy a local workspace through Resilis over MCP, the Model Context Protocol. This route needs Git and an agent with local file and command access; GitHub is unnecessary. Review the source, requested access, target, build settings, and secrets before authorizing the deployment.

Deployment limits and costs

Custom domains are unavailable on connected compute and S3-backed static sites. App rollback does not restore data or reverse database migrations. Review the target capabilities and usage rates before adapting this example.