Skip to content

Node Express API

A REST API built with Node.js and Express. Single container, single service, no database -- demonstrating how to deploy a Node.js application on AppMecca.

Overview
Repository git@gitlab.com:appmecca-sample-apps/node-express-api.git
Tech Stack Node.js 20 / Express
Services api (port 3000)
Database None
Cache None
URL Pattern https://node-express-api-api.{env}.appmecca.net

What This App Demonstrates

  • Deploying a Node.js application on AppMecca
  • API service naming conventions (using api instead of web)
  • Standard Express project structure with health endpoint
  • Production Node.js container patterns (npm ci --only=production)

appmecca.yaml

containers:
  - name: api
    dockerfile: Dockerfile
    context: .

deploy:
  - name: api
    container: api
    port: 3000
    health_check:
      path: /health

The configuration follows the same pattern as any single-container app. The service is named api rather than web to reflect that it serves a REST API, but this is purely a naming choice -- AppMecca treats them identically.

Step-by-Step Deployment

1. Register the app

mecca register git@gitlab.com:appmecca-sample-apps/node-express-api.git -e dev

2. Build the container

mecca build trigger -e dev -g git@gitlab.com:appmecca-sample-apps/node-express-api.git
Expected output 
Build started: build-xxxxxxxx
Cloning repository...
Building container: api
Pushing to the image registry: appmecca-dev-node-express-api
Build complete. Duration: 38s

3. Deploy

mecca app deploy -e dev node-express-api
Expected output 
Deploying node-express-api to dev...
Deployment queued: deploy-xxxxxxxx
Waiting for agents...
Container started: node-express-api-api
Health check passed: /health -> 200 OK
Deployment complete.

Services:
  api: https://node-express-api-api.dev.appmecca.net

4. Verify

mecca queue status takes a queue action id, so to check on the app itself use:

mecca app show -e dev node-express-api

Test the API directly:

curl https://node-express-api-api.dev.appmecca.net/health

{"status": "healthy"}

Key Concepts

Service naming

The service name in appmecca.yaml is a label you choose. Common conventions:

Name Typical use
web General-purpose web server
api REST or GraphQL API
frontend Client-facing UI
backend Server-side logic

The name appears in logs, status output, and in the URL. The service name is always part of the hostname — an app with a single service named api is reached at node-express-api-api.{env}.appmecca.net, not at a bare node-express-api.{env}.appmecca.net. Pick the name with that in mind.

Node.js production containers

A production Node.js Dockerfile typically uses npm ci --only=production to install only production dependencies, skipping devDependencies like test frameworks and linters. This keeps the image smaller and reduces the attack surface.

Use a .dockerignore file

Add node_modules, .git, and test directories to .dockerignore to prevent them from being copied into the build context. This speeds up builds and keeps images clean.

Reading build logs

mecca build trigger returns as soon as the build is queued. To read the output, take the build id it printed and pass it to mecca build logs:

mecca build list -e dev                 # find the build id
mecca build logs -e dev <build-id>      # read the output

mecca build status -e dev <build-id> reports whether it is still running, succeeded, or failed.

What's Next?