Docker Deployment

This guide covers deploying the Stripe Payments API using Docker, including local development with Docker Compose and pulling the pre-built image from Docker Hub.

Overview

The API is containerized using Docker with a production-ready configuration. A pre-built image is available on Docker Hub for quick deployment.

Docker Hub Image

luis159/stripe-back:latest

Base Image

node:20-alpine

Dockerfile Configuration

The API uses an optimized Dockerfile for production deployments:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --omit=dev

COPY . .

ENV NODE_ENV=production
ENV PORT=3000

EXPOSE 3000

CMD ["npm", "start"]

Key Features:

Uses Alpine Linux for minimal image size
Installs only production dependencies with npm ci --omit=dev
Sets production environment by default
Exposes port 3000
Runs with npm start command

Method 1: Docker Compose (Local Development)

The recommended approach for local development is using Docker Compose.

Create Environment File

Create a .env file in your project root with your Stripe credentials:

STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx
PORT=3000
NODE_ENV=production

Never commit your .env file to version control. Add it to .gitignore.

Docker Compose Configuration

The docker-compose.yml file is configured as follows:

services:
  api:
    build: .
    container_name: stripe-back-api
    env_file:
      - .env
    ports:
      - "3000:3000"
    restart: unless-stopped

Configuration Details:

build: Builds from the local Dockerfile

container_name: Names the container stripe-back-api

env_file: Loads environment variables from .env

ports: Maps container port 3000 to host port 3000

restart: Automatically restarts the container unless explicitly stopped

Start the Application

docker-compose up -d

The -d flag runs the container in detached mode (background).

View Logs

docker-compose logs -f api

Stop the Application

docker-compose down

Method 2: Pre-built Docker Hub Image

For quick deployment without building from source, use the pre-built image.

Pull the Image

docker pull luis159/stripe-back:latest

Run the Container

docker run -d \
  --name stripe-back-api \
  -p 3000:3000 \
  -e STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxx \
  -e STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx \
  -e NODE_ENV=production \
  --restart unless-stopped \
  luis159/stripe-back:latest

Parameters:

-d: Run in detached mode

--name: Container name

-p 3000:3000: Port mapping (host:container)

-e: Environment variables

--restart: Restart policy

Using Environment File

Alternatively, use an environment file:

docker run -d \
  --name stripe-back-api \
  -p 3000:3000 \
  --env-file .env \
  --restart unless-stopped \
  luis159/stripe-back-api:latest

Verify the Container

docker ps

Expected Output:

CONTAINER ID   IMAGE                        STATUS         PORTS
abc123def456   luis159/stripe-back:latest   Up 10 seconds  0.0.0.0:3000->3000/tcp

View Container Logs

docker logs -f stripe-back-api

Method 3: Build from Source

If you need to customize the image or work with local changes:

Clone the Repository

git clone <repository-url>
cd stripe-back

Build the Image

docker build -t stripe-back:local .

Run Your Custom Image

docker run -d \
  --name stripe-back-api \
  -p 3000:3000 \
  --env-file .env \
  --restart unless-stopped \
  stripe-back:local

Environment Variables

Required environment variables for deployment:

Variable	Description	Required	Example
`STRIPE_SECRET_KEY`	Stripe API secret key	Yes	`sk_test_...`
`STRIPE_WEBHOOK_SECRET`	Webhook signing secret	Yes	`whsec_...`
`PORT`	Application port	No	`3000` (default)
`NODE_ENV`	Node environment	No	`production` (default)

The Dockerfile sets NODE_ENV=production and PORT=3000 by default. You can override these with environment variables.

Health Check

Verify the API is running:

curl http://localhost:3000/

Expected Response:

{
  "status": true,
  "message": "API is running"
}

Production Deployment Tips

Use Specific Tags

Instead of latest, use specific version tags in production:

docker pull luis159/stripe-back:v1.0.0

Resource Limits

Set memory and CPU limits for production:

docker run -d \
  --memory="512m" \
  --cpus="1.0" \
  luis159/stripe-back:latest

Volume Mounting

If your app needs persistent storage:

docker run -d \
  -v /path/on/host:/app/data \
  luis159/stripe-back:latest

Network Configuration

For multi-container setups, use Docker networks:

docker network create stripe-network
docker run -d --network stripe-network luis159/stripe-back:latest

Docker Compose for Production

For production deployments with additional services:

docker-compose.prod.yml

services:
  api:
    image: luis159/stripe-back:latest
    container_name: stripe-back-api
    env_file:
      - .env.production
    ports:
      - "3000:3000"
    restart: always
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Deploy with:

docker-compose -f docker-compose.prod.yml up -d

Troubleshooting

Container exits immediately

Check the logs for errors:

docker logs stripe-back-api

Common issues:

Missing required environment variables
Port 3000 already in use
Invalid Stripe credentials

Cannot connect to the API

Verify the container is running: docker ps
Check port mapping: docker port stripe-back-api

Test from inside the container:

docker exec stripe-back-api curl http://localhost:3000

Environment variables not loading

Ensure your .env file:

Is in the same directory as your docker-compose.yml
Has no quotes around values (unless needed)
Uses the correct variable names
Has Unix line endings (LF, not CRLF)

Build fails with dependency errors

If building from source fails:

# Clear Docker cache and rebuild
docker build --no-cache -t stripe-back:local .

Container Management

Common Commands

# Stop container
docker stop stripe-back-api

# Start container
docker start stripe-back-api

# Restart container
docker restart stripe-back-api

# Remove container
docker rm stripe-back-api

# Remove image
docker rmi luis159/stripe-back:latest

# Execute command in container
docker exec -it stripe-back-api sh

# View resource usage
docker stats stripe-back-api

Next Steps

Configure webhook testing in your Docker environment
Review error handling patterns
Follow the complete payment workflow

Get Started

Guides

Overview

Docker Hub Image

Base Image

Dockerfile Configuration

Method 1: Docker Compose (Local Development)

Method 2: Pre-built Docker Hub Image

Method 3: Build from Source

Environment Variables

Health Check

Production Deployment Tips

Use Specific Tags

Resource Limits

Volume Mounting

Network Configuration

Docker Compose for Production

Troubleshooting

Container Management

Common Commands

Next Steps

Build docs developers (and LLMs) love

Get Started

Guides

​Overview

Docker Hub Image

Base Image

​Dockerfile Configuration

​Method 1: Docker Compose (Local Development)

​Method 2: Pre-built Docker Hub Image

​Method 3: Build from Source

​Environment Variables

​Health Check

​Production Deployment Tips

Use Specific Tags

Resource Limits

Volume Mounting

Network Configuration

​Docker Compose for Production

​Troubleshooting

​Container Management

​Common Commands

​Next Steps

Build docs developers (and LLMs) love

Overview

Dockerfile Configuration

Method 1: Docker Compose (Local Development)

Method 2: Pre-built Docker Hub Image

Method 3: Build from Source

Environment Variables

Health Check

Production Deployment Tips

Docker Compose for Production

Troubleshooting

Container Management

Common Commands

Next Steps