Deploy a Remix App

Remix (opens in a new tab) is a full stack web framework focused on making it simpler to build modern, standards-aligned web apps that run anywhere. With features like nested routes, progressive enhancement, and error boundaries, Remix allows you to create great user experiences built on foundational web technologies.

This guide explains how to deploy a Remix application to Koyeb using:

Git-driven deployment to automatically build and deploy a new version of your application each time a change is detected on your branch.
Pre-built containers you can deploy from any public or private registry.

To successfully follow this documentation, you will need to have a Koyeb account (opens in a new tab). You can optionally install the Koyeb CLI if you prefer to follow this guide without leaving the terminal.

You can deploy and preview the Remix application from this guide using the Deploy to Koyeb button below.

(opens in a new tab)

You can consult the repository on GitHub (opens in a new tab) to find out more about the example application that this guide uses.

Create the Remix app

Get started by creating a minimalistic Remix application that we will deploy to Koyeb. You will need Node.js (opens in a new tab) installed on your machine.

To generate a new Remix application, run the npx create-remix@latest command:

npx create-remix@latest

Remix will ask some questions about how you want to configure your project. For this demonstration, we'll select:

example-remix as the name of the project
"Just the basics" instead of a specific stack
"Remix App Server" as our deployment target
Typescript as our language
"Yes" to run npm install for the project

Your project will be configured in a new directory matching the name you selected. The project's dependencies will be downloaded and installed, leaving you with a basic, but functional project directory to get started.

Move into the new project directory:

cd example-remix

If you run tree -a -I node_modules to show the project hierarchy (excluding the node_modules dependencies), a directory structure similar to this should be present:

.
├── app
│   ├── entry.client.tsx
│   ├── entry.server.tsx
│   ├── root.tsx
│   └── routes
│       └── _index.tsx
├── .eslintrc.js
├── .gitignore
├── package.json
├── package-lock.json
├── public
│   └── favicon.ico
├── README.md
├── remix.config.js
├── remix.env.d.ts
└── tsconfig.json

Run the Remix app locally

With the project bootstrapped and the dependencies installed, start the development server by typing:

npm run dev

In your web browser, navigate to http://127.0.0.1:3000 to see the default Remix landing page. It is rather basic by default, showing just a heading and some documentation links, but it is enough to validate that the development server is able to serve your project successfully.

Press CTRL-C to stop the development server after verifying.

This example application should run on any modern version of Node.js. If your application requires a specific Node.js version, add or set the engines section in your package.json file. Consult the build with Node.js page to learn more.

Push the project to GitHub

Once you've verified that the project runs locally, create a new Git repository to save your work.

Run the following commands to create a new Git repository within the project's root directory, commit the project files, and push changes to GitHub.

Remember to replace the values of <YOUR_GITHUB_USERNAME> and <YOUR_REPOSITORY_NAME> with your own information:

git init
git add .
git commit -m "Initial commit"
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
git push -u origin main

Deploy the Remix app to Koyeb using git-driven deployment

To deploy the Remix app on Koyeb, using the control panel (opens in a new tab) follow the steps below:

Click Create Web Service on the Overview tab of the Koyeb control panel.
Select GitHub as the deployment option.
Choose the GitHub repository and branch containing your application code. Alternatively, you can enter our public Remix example repository (opens in a new tab) into the Public GitHub repository at the bottom of the page: https://github.com/koyeb/example-remix.
Name the App and Service, for example example-remix.
Click the Deploy button.

A Koyeb App and Service will be created. Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with .koyeb.app.

Deploy the Remix app on Koyeb using a pre-built container

As an alternative to using git-driven deployment, you can deploy a pre-built container from any public or private registry. This can be useful if your application needs specific system dependencies or you need more control over how the build is performed.

To dockerize the Remix application, start by adding a file called .dockerignore to the project's root directory. Paste the following contents to limit the files copied to the Docker image:

.dockerignore

Dockerfile
.dockerignore
.git
node_modules
npm-debug.log
/.cache
/build
/public/build
.env
README.md

Afterwards, create a Dockerfile in your project root directory and copy the content below:

Dockerfile

FROM node:18-alpine AS base
 
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
 
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build && npm cache clean --force
 
FROM base AS runner
WORKDIR /app
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 remix
COPY --from=builder /app .
USER remix
EXPOSE 3000
ENV PORT 3000
CMD ["npm", "run", "start"]

The Dockerfile above provides the minimum requirements to run the Remix application. You can easily extend it depending on your needs.

To build and push the Docker image to a registry and deploy it on Koyeb, refer to the page on deploying pre-built container images.

Nuxt Qwik