Tutorial: Create NodeJS App Docker Container and Install on Unraid

.

This tutorial is about installing and running a NodeJS app on Unraid using a Docker Container. It seems this is rare use case, people have worked out how to do this themselves or people just don't blog about it. Whatever the reason information is relatively thin on the ground.

If you do find this tutorial useful please shout me a coffee as it really makes a difference and enables me to continue to create new content.

Pre-requisites

For this example I am running:

• A computer running Windows 11.
• Visual Studio Code v1.101.2 (installed on Windows PC).
• A NodeJS app (you want to install on Unraid)
• Docker Hub account.
• Docker Desktop For Windows.
• HeidiSQL.
• Unraid 6.2.10

High Level Process

To install a NodeJS app on Unraid includes six main steps as outlined below. They are elaborated in more detain within the tutorial.

1. The package.json file must have a start script
2. Create a Dockerfile
3. BUILD a Docker image for your NodeJS application.
4. Test the Docker image "locally".
5. Push image to Docker Hub.
6. Deploy Docker Hub image on Unraid using the Web UI
7. Buy me a coffee

Step 1

Step 1: For your NodeJS application make sure the package.json has a start script.

Code

📋

    
  {
  "name": "00-2025-a0-restapi-crud-tutorial",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^5.1.0",
    "express-json": "^1.0.0",
    "mariadb": "^3.4.5"
  }
}
    
    

Starting your NodeJS App: The code you place in 'Start' will be the first code run when you start the Docker container. In this example the code that executes when you first start the NodeJS web application is:
- node index.js

Step 2: Create a Dockerfile

Step 2: Create a Dockerfile in project root.

In this example, Express app listening on port 8102.

Code

📋

    
# Use an official Node.js runtime as a parent image
# Specifies the base image. node:24-alpine is a lightweight 
# official Node.js image with Node.js version 24.
FROM node:24-alpine

# Set the working directory in the container
# All subsequent commands will execute within this directory.
WORKDIR /usr/src/app

# Copy package.json and package-lock.json to install dependencies
COPY package*.json ./

# Install application dependencies
RUN npm install

# Copy the rest of the application code
COPY . .

# Expose the port your app listens on
# Informs Docker that the container will listen on port XXXX. 
# Replace XXXX with the actual port your Node.js application uses.
EXPOSE 8102

# Command to run the application
# Defines the command to run when 
# the container starts. Replace XXXX with your main application entry file.
CMD ["node", "index.js"]
    
    

Step 3: Build Docker Image

Step 3: BUILD your docker image for your application. In the Visual Studio Code Terminal run the following command. Note: The period at the end is part of the command.

Code

📋

    
docker build -t yourappname .
    
    

You can confirm that the image has been created by viewing the list of your docker images using the command:

Code

📋

    
docker images
    
    

You will see a list of all your Docker images (see below):

Alternatively you can see your Docker images in the Docker Desktop Windows application (see image below):

Step 4: Test Docker Image - Locally

Step 4: Test the Docker image "locally" to check that it is working before pushing to Docker Hub. Run the Docker image.

Code

📋

    
docker run -d --name localnameforcontainer -p 8102:8102 crudrestapi1:latest
    
    

The Docker run command is explained in more detail below:

Part	Meaning
docker run	Creates and starts a new container from a Docker image.
-d	Runs the container in detached mode (in the background).
--name localnameforcontainer	Assigns a custom name to the container so you can reference it easily later.
-p 8102:8102	Port mapping: Maps port 8102 on the host to port 8102 in the container.
crudrestapi8102:latest	Specifies the Docker image name and tag to run the container from.

Check that the Docker container is running.

Code

📋

    
docker ps
    
    

In the Visual Studio Code Terminal it looks like this:

Since we are using port: 8102 in this example if the container is running it will have:
status Up; and
port 0.0.0.0:8102->8102.

Part	Meaning
0.0.0.0	The port is accessible from all network interfaces on the host machine (i.e., any IP address of your computer).
8102 (before arrow)	The host port — this is the port on your Windows PC that is open to the outside world.
->	Indicates the mapping direction from host to container.
8102 (after arrow)	The container port — this is the internal port your Node.js app is listening on inside the Docker container.
/tcp	The protocol used for communication (TCP is standard for HTTP and REST APIs).

Since this is a REST API web server we can test that is running properly by testing an endpoint. Assuming an endpoint of "customers" into our browser we can type:

Code

📋

    
http://localhost:8102/customers/1
    
    

Since it returns the following (see image below), we know at least running the docker container locally off the development computer the container is working as expected.

As a double check, you can stop the container, re-enter the url testing your endpoint and you should get no response. To stop a single container or all containers you can use either of these commands:

Code

📋

    
# Stopping a single container
docker stop <container_name_or_id>

#Stopping all running containers
docker stop $(docker ps -q)
    
    

Great!!! If the Docker Container is working when run locally you can now push it to your Docker Hub account.

Step 5: Push image to Docker Hub

Step 5: Push image to Docker Hub: You can push your Docker image to your Docker Hub if you wish. You will need a Docker Hub access token to complete this. In Docker Hub 'Generate new token".

Log into Docker Hub with your user credentials.

Code

📋

    
docker login
    
    

Tag your local image with your Docker Hub repository name. For example, the repository 'crudrestapi8102' will be tagged with this command:

Code

📋

    
# 1. Tag the image
docker tag crudrestapi8102:latest  <userAccountName>/crudrestapi8102:latest
    
    

In the Visual Studio Code Terminal it looks like this:

Push your local repository to Docker Hub. For example, the repository 'crudrestapi8102' will be pushed with this command:

Code

📋

    
# 2. Push to Docker Hub
docker push userAccountName/crudrestapi8102:latest
    
    

In the Visual Studio Code Terminal window it looks like this:

The repository will now appear in your Docker Hub account (see image below):

Get the Docker Pull information. Go to the Tags tab in Docker Hub and you will see docker push command to push a new Tag (top right in image, see below) as well as a docker pull command (bottom right in image, see below).

Pay attention to the docker pull command as we will use the the information from Docker Hub to pull the image to a Docker Container on your Unraid system in the next step.

Note: In this example the text we will use from Docker Hub is: userAccountName/crudrestapi8102:latest. You do NOT include the "docker pull" part of the command.

Step 6: Deploy Docker Hub image on Unraid using the Web UI

Okay, with your Docker image now up on Docker Hub you can use this image to install into a Docker Container on your Unraid system.

In your Docker Containers menu click on 'Add Container'.

Complete Docker Container Template Enter the following:

• Name: [Enter name you will use for your Docker container]
• Repository: [Enter Docker Pull text obtained in previous step]

Add port: Click on Add another Path, Port... button and then add a reference to a port. As our NodeJS app is using port 8102 we will add this information as per the screenshot below:

Click on the 'Add' button and the reference to the Port is added to the Docker Container.

The completed Docker template is shown below. Click on the 'Apply' button. The Docker Container for your application is now installed and running on Unraid.

Test your application. Now test that your NodeJS application is running as intended.

Congratulations!!! You have succesfully intalled a NodeJS application into a Docker Container on Unraid./p>

Please support this channel: Have I saved you minutes, hours or even days of scouring the internet and youTube to find an actual working solution.

It takes me time and effort to both find a working solution and then write everything up. Please consider buying me a coffee so I can keep producing useful content, especially if I've made your life easier. Cheers!

Believe it or not a coffee goes a long way so if I've helped you out a coffee would be great. Cheers!