First App Deployment

This guide will walk you through deploying your first Platformatic Watt application to ICC on any Kubernetes cluster. Unlike the Getting Started guide which uses desk for local development, this guide provides a generic approach that works with any Kubernetes cluster (EKS, GKE, AKS, on-premise, etc.).

Prerequisites

• ICC already installed and running on your Kubernetes cluster (see Installation)
• kubectl configured to access your cluster
• Docker installed for building images
• Access to a container registry (Docker Hub, ECR, GCR, ACR, or private registry)
• A Platformatic Watt application ready to deploy

Step 1: Prepare Your Application

Your application needs a Dockerfile optimized for ICC deployment.

First, ensure @platformatic/watt-extra is in your package.json dependencies with a specific version:

{
  "dependencies": {
    "@platformatic/watt-extra": "^1.0.0"
  }
}

Then create your Dockerfile:

FROM node:22-alpine
ENV APP_HOME=/home/app/node/
RUN mkdir -p $APP_HOME/node_modules && chown -R node:node $APP_HOME

WORKDIR $APP_HOME

# Copy package files first for better caching
COPY ./package.json ./package.json
COPY ./package-lock.json ./package-lock.json
RUN npm ci

COPY --chown=node:node . .

# Default Watt port
EXPOSE 3042

# Prometheus port for metrics
EXPOSE 9090

# ICC connection - adjust if ICC is in a different namespace
ENV PLT_ICC_URL="http://icc.platformatic.svc.cluster.local"

# Server must listen on all interfaces to be reachable
ENV PLT_SERVER_HOSTNAME=0.0.0.0

CMD [ "npx", "watt-extra", "start" ]

Important Environment Variables

• PLT_ICC_URL: URL to ICC service. Adjust if ICC is installed in a different namespace
• PLT_SERVER_HOSTNAME: Must be 0.0.0.0 to accept connections from outside the container

Step 2: Build and Push Docker Image

Build your Docker image and push it to your container registry (Docker Hub, ECR, GCR, ACR, or your private registry):

docker build -t your-registry.com/my-watt-app:v1.0.0 .
docker push your-registry.com/my-watt-app:v1.0.0

Make sure you’re authenticated to your registry before pushing.

Step 3: Create Kubernetes Manifests

Create a minimal deployment manifest for your application. Save this as deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-watt-app
  namespace: platformatic
spec:
  selector:
    matchLabels:
      app: my-watt-app
  template:
    metadata:
      labels:
        app: my-watt-app
        platformatic.dev/monitor: prometheus
    spec:
      containers:
      - name: my-watt-app
        image: your-registry.com/my-watt-app:v1.0.0
        ports:
        - name: app
          containerPort: 3042
          protocol: TCP
        - name: metrics
          containerPort: 9090
          protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
  name: my-watt-app
  namespace: platformatic
spec:
  ports:
  - name: app
    port: 3042
    targetPort: 3042
  - name: metrics
    port: 9090
    targetPort: 9090
  selector:
    app: my-watt-app

This is the minimum configuration needed for ICC. The PLT_ICC_URL and PLT_SERVER_HOSTNAME environment variables are already set in the Dockerfile from Step 1. Add resource limits, probes, replicas, environment variable overrides, and other configurations as needed for your environment.

Step 4: Deploy to Kubernetes

Apply the manifests to your cluster:

kubectl apply -f deployment.yaml

Step 5: Verify Deployment

Check Pod Status

# Watch pods starting up
kubectl get pods -n platformatic -l app=my-watt-app --watch

# Check pod details if there are issues
kubectl describe pod -n platformatic -l app=my-watt-app

Check Logs

kubectl logs -n platformatic -l app=my-watt-app --tail=100 -f

Verify Service

kubectl get svc -n platformatic my-watt-app

Check in ICC UI

1. Log in to your ICC dashboard
2. Navigate to the Watts page
3. Your Watt should appear in the list (may take a few moments)
4. Click on your application to see details, metrics, and logs

Troubleshooting

Application Not Appearing in ICC

Verify:

1. Pod is running: kubectl get pods -n platformatic
2. PLT_ICC_URL environment variable is set correctly
3. Network connectivity between your app and ICC service
4. Application is in the correct namespace