docker-node-serverless
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 22 (Alpine) — AWS Lambda supports nodejs22.x (see: Lambda runtimes).
What's Included
| Component |
Details |
| Node.js |
22 (Alpine base image) |
| Serverless Framework |
v4.33.1 (pinned via SERVERLESS_VERSION ENV) |
| AWS CLI v2 |
Alpine package install |
| Package managers |
npm (bundled), pnpm (global), Yarn (bundled) |
| Python 3 + pip |
For plugins / build tooling needing Python |
| Shell & utils |
bash, less, groff, ca-certificates |
| User |
Non-root serverless (UID 1001), WORKDIR /app |
Image Tags / Branch Mapping
| Node Line |
Branch / Tag |
Status |
| 22 |
22.x |
Recommended (current focus) |
| 20 |
20.x |
Still supported (earlier Lambda support window) |
| 18 |
18.x |
Approaching end of support |
| 16 |
16.x |
Deprecated (legacy only) |
master tracks the active major (Node 22). Pin a major tag (22.x) for deterministic CI builds.
Quick Start
Pull the image:
docker pull jch254/docker-node-serverless:22
Check versions:
docker run --rm jch254/docker-node-serverless:22 serverless --version
docker run --rm jch254/docker-node-serverless:22 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:22 \
serverless deploy --stage dev
Bitbucket Pipelines Example
pipelines:
default:
- step:
image: jch254/docker-node-serverless:22
caches:
- node
script:
- pnpm install # or npm ci / yarn install
- serverless deploy --stage dev
GitHub Actions Example
name: Deploy
on: [push]
jobs:
deploy:
runs-on: ubuntu-latest
container: jch254/docker-node-serverless:22
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
AWS CodeBuild buildspec.yml Example
version: 0.2
phases:
install:
runtime-versions: {}
build:
commands:
- pnpm install --frozen-lockfile
- serverless deploy --stage prod
Package Managers
Use whichever you prefer:
# pnpm
pnpm install
serverless package
# npm
npm ci
serverless deploy
# Yarn
yarn install --frozen-lockfile
serverless remove
AWS Credentials
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:22 serverless info
Non-Root User & Permissions
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:22 chown -R 1001:1001 /app
Or run a one-off global install:
docker run --rm -u 0 jch254/docker-node-serverless:22 npm install -g serverless-plugin-aws-alerts
Extending the Image
FROM jch254/docker-node-serverless:22
RUN npm install -g serverless-plugin-aws-alerts
Build:
docker build -t my/serverless-image:22 .
Upgrading Notes (Node 20 -> 22, Serverless 3 -> 4)
Review the following when upgrading:
- Update any
runtime fields in serverless.yml to nodejs22.x (if not deploying via container images).
- Serverless v4 drops deprecated CLI flags—remove legacy options (e.g. old
--aws-s3-accelerate if used).
- Rebuild native dependencies (node-gyp) to target Node 22 ABI if packaging layers/binaries.
- Verify plugins are compatible; update to latest maintained versions.
Troubleshooting
| Symptom |
Resolution |
| EACCES on write to /app |
Ensure host directory ownership or run with -u 0 briefly to fix perms |
| AWS auth errors |
Confirm env vars, or mount ~/.aws with correct profile |
| Plugin missing system libs |
Create derived image adding apk add <lib> |
| Slow cold start bundle size |
Use serverless package + prune dev deps, leverage layers |
Reference Links
Contributing
PRs welcome: keep layers minimal, versions pinned where helpful, and document added tools.
License
MIT
Feedback & improvements welcome.