Minimal, repeatable build & deployment container for AWS Serverless Framework services. Intended for CI environments like Bitbucket Pipelines, AWS CodeBuild, GitHub Actions, GitLab CI, etc.

Baseline runtime: Node.js 18 (Alpine) — AWS Lambda supports nodejs18.x (see: Lambda runtimes).

master (for this branch) targets Node 18. Pin the major tag (18.x) for deterministic CI builds. Plan migration to 20.x soon due to support window.

Pull the image:

docker pull jch254/docker-node-serverless:18

Check versions:

docker run --rm jch254/docker-node-serverless:18 serverless --version
docker run --rm jch254/docker-node-serverless:18 node -v

Deploy (mount your service directory):

docker run --rm -it \
  -v "$PWD":/app \
  -w /app \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e AWS_REGION=us-east-1 \
  jch254/docker-node-serverless:18 \
  serverless deploy --stage dev

pipelines:
  default:
    - step:
  image: jch254/docker-node-serverless:18
        caches:
          - node
        script:
          - pnpm install # or npm ci / yarn install
          - serverless deploy --stage dev

name: Deploy
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
  container: jch254/docker-node-serverless:18
    steps:
      - uses: actions/checkout@v4
      - name: Install deps
        run: pnpm install --frozen-lockfile
      - name: Deploy
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: us-east-1
        run: serverless deploy --stage prod

version: 0.2
phases:
  install:
    runtime-versions: {}
  build:
    commands:
      - pnpm install --frozen-lockfile
      - serverless deploy --stage prod

Use whichever you prefer:

# pnpm
pnpm install
serverless package

# npm
npm ci
serverless deploy

# Yarn
yarn install --frozen-lockfile
serverless remove

Provide credentials via environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, optional AWS_SESSION_TOKEN, AWS_REGION) or mount a credentials directory:

docker run --rm \
  -v $HOME/.aws:/home/serverless/.aws:ro \
  -v $PWD:/app -w /app \
  jch254/docker-node-serverless:18 serverless info

The image runs as serverless (UID 1001). If you encounter permission issues writing to a bind mount created by root (e.g., on some CI agents), you can temporarily override the user:

docker run --rm -u 0 jch254/docker-node-serverless:18 chown -R 1001:1001 /app

Or run a one-off global install:

docker run --rm -u 0 jch254/docker-node-serverless:18 npm install -g serverless-plugin-aws-alerts

FROM jch254/docker-node-serverless:18
RUN npm install -g serverless-plugin-aws-alerts

Build:

docker build -t my/serverless-image:18 .

Review the following when upgrading:

• Update runtime in serverless.yml to nodejs20.x (or directly nodejs22.x if skipping 20) when upgrading.
• Serverless v4 drops deprecated CLI flags—remove legacy options (e.g. old --aws-s3-accelerate if used).
• Rebuild native dependencies (node-gyp) after moving from Node 18 (ABI change at 20, again at 22).
• Verify plugin compatibility; upgrade outdated plugins before runtime jump.

• Serverless Framework: https://www.serverless.com/
• AWS Lambda runtimes: https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html
• pnpm: https://pnpm.io/

PRs welcome: keep layers minimal, versions pinned where helpful, and document added tools.

MIT

Feedback & improvements welcome.