Skip to main content

​
Overview

StockAPI can be easily deployed using Docker, providing a consistent environment across different platforms. This guide covers both using the pre-built image from GitHub Packages and building your own image.

​
Using the Pre-built Image

The easiest way to run StockAPI is by using the official Docker image hosted on GitHub Container Registry.
1

Pull the image

Download the latest StockAPI image from GitHub Packages:
docker pull ghcr.io/marcosdaag/stockapi:latest
2

Run the container

Start the API container with port mapping:
docker run -p 3000:3000 ghcr.io/marcosdaag/stockapi:latest
The API will be accessible at http://localhost:3000
The pre-built image comes with all dependencies installed but you’ll still need to provide environment variables for the API to function properly.

​
Running with Environment Variables

To run the container with your environment variables, you have two options:

​
Option 1: Using Environment File

1

Create .env file

Create a .env file with all required variables:
.env
APP_NAME="Stock Management System"
PORT=3000
MONGO_URI="mongodb+srv://username:[email protected]/database"
JWT_SECRET="your-secret-key"
EMAIL_USER="[email protected]"
EMAIL_PASS="your-email-password"
RESEND_API_KEY="re_your_api_key"
2

Run with env file

Use the --env-file flag to load your environment variables:
docker run -p 3000:3000 --env-file .env ghcr.io/marcosdaag/stockapi:latest

​
Option 2: Using Individual -e Flags

Pass environment variables directly in the docker run command: 
docker run -p 3000:3000 \
  -e APP_NAME="Stock Management System" \
  -e PORT=3000 \
  -e MONGO_URI="mongodb+srv://user:[email protected]/db" \
  -e JWT_SECRET="your-secret" \
  -e EMAIL_USER="[email protected]" \
  -e EMAIL_PASS="password" \
  -e RESEND_API_KEY="re_key" \
  ghcr.io/marcosdaag/stockapi:latest
Be careful when passing sensitive environment variables via command line, as they may be visible in your shell history.

​
Port Mapping

The StockAPI Docker container exposes port 3000 by default. You can map it to any available port on your host machine: 
docker run -p 3000:3000 ghcr.io/marcosdaag/stockapi:latest

​
Building Your Own Image

If you want to build the Docker image from source, you can use the included Dockerfile.
1

Review the Dockerfile

The project includes a Dockerfile that uses Node.js 20:
Dockerfile
# Imagen base oficial de Node
FROM node:20

# Crea y usa un directorio de trabajo
WORKDIR /app

# Copia los archivos de configuración primero
COPY package*.json ./

# Instala las dependencias
RUN npm install

# Copia el resto del código de tu proyecto
COPY . .

# Expone el puerto en el que corre tu API
EXPOSE 3000

# Comando para ejecutar la app
CMD ["npm", "start"]
2

Build the image

From the project root directory, build the Docker image:
docker build -t stockapi:local .
3

Run your custom image

Run a container from your newly built image:
docker run -p 3000:3000 --env-file .env stockapi:local

​
Running in Detached Mode

To run the container in the background (detached mode): 
docker run -d -p 3000:3000 --env-file .env --name stockapi ghcr.io/marcosdaag/stockapi:latest

​
Managing the Container

docker logs stockapi

​
Docker Compose

For easier management, you can create a docker-compose.yml file:
docker-compose.yml
version: '3.8'

services:
  stockapi:
    image: ghcr.io/marcosdaag/stockapi:latest
    ports:
      - "3000:3000"
    env_file:
      - .env
    restart: unless-stopped
    environment:
      - NODE_ENV=production
Then run with: 
docker-compose up -d

​
Verifying the Deployment

Once the container is running, verify it’s working correctly:
1

Check container status

docker ps
You should see your StockAPI container running.
2

Check application logs

docker logs stockapi
Look for the success messages:
✅ Conexión a MongoDB Atlas establecida correctamente
✅ Servidor funcionando en el puerto 3000
3

Test the API

Make a test request to verify the API is responding:
curl http://localhost:3000

​
Troubleshooting

​
Container Exits Immediately

If your container starts and then immediately exits:
  1. Check the logs for error messages: 
    docker logs stockapi
  2. Most commonly, this is due to:
    • Missing or invalid MONGO_URI environment variable
    • MongoDB connection failure
    • Port conflict

​
Cannot Connect to MongoDB

If you see database connection errors:
  • Verify your MONGO_URI is correct
  • Ensure your MongoDB Atlas IP whitelist includes the Docker container’s IP
  • Consider using 0.0.0.0/0 in MongoDB Atlas for testing (not recommended for production)
  • See Database Connection for more details

​
Port Already in Use

If port 3000 is already in use: 
# Use a different host port
docker run -p 8080:3000 --env-file .env ghcr.io/marcosdaag/stockapi:latest

​
Permission Denied

If you get permission errors when pulling from GitHub Packages: 
# The image is public, but you may need to authenticate
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

​
Production Considerations

When deploying to production:
  • Use Docker secrets or a secure secret management solution instead of .env files
  • Set up proper logging and monitoring
  • Use a reverse proxy like Nginx for SSL/TLS termination
  • Implement health checks
  • Consider using container orchestration (Kubernetes, Docker Swarm)

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us