Sign in Get started

SETUP GUIDES · SELF-HOSTED

Run the Claspine engine (Node.js, Python, Go and other stacks)

Self-hosted Claspine for any language: a Docker image next to your app, called over HTTP or with the Node SDK.

⏱ About 15 minutes

Spring Boot applications add Claspine as a library. Every other backend runs the Claspine engine, a ready-made Docker image from Claspine Packages, next to its database and calls it over HTTP: sign-in, permissions, files, AI, payments and audit, with no Java in your app. The Node starter on Self-hosted → Setup does all of this for you.

Words you’ll see

License key
The SPINE-FOUNDER-… or SPINE-AGENCY-… code that identifies your self-hosted license. Quote it when you contact support. It is not a password and cannot download anything by itself.
Download token
A secret starting with spk_ that lets your builds download Claspine’s packages. It works like a password for Maven and npm: keep it in an environment variable or a CI secret, never in your code.
Package registry
A server that hands out code libraries to build tools. Maven (Java) and npm (JavaScript) download the libraries your project lists from registries. Claspine Packages is Claspine’s private one, at api.claspine.com/packages.

Before you start

  • A self-hosted license and a download token (see Install self-hosted Claspine).
  • Docker with Compose, and PostgreSQL (the Compose file below starts one).

Steps

  1. Sign in to the registry with your token: echo "$SPINE_PACKAGES_TOKEN" | docker login api.claspine.com -u license --password-stdin.
  2. Create a service key for your backend: docker run --rm api.claspine.com/claspine/engine:<version> generate-service-key app-backend. Give the key to your backend as SPINE_API_KEY and put the PLATFORM_ENGINE_SERVICEKEYS_0_* lines it prints in spine-engine.env (the engine keeps only the digest).
  3. Start the engine with the Compose file below. At the first start it sets your application up (product, hosts, sign-in).
  4. Call it from your backend: the Node SDK (@grahmur-org/claspine-client) or HTTP with the header X-Spine-Api-Key. Browsers never get the key; they reach Claspine through your routes.
  5. For AI, give the engine one provider key (a free Groq key is enough to start: PLATFORM_LLM_GROQ_APIKEYREFERENCE=env:GROQ_API_KEY). For files, configure your bucket with the PLATFORM_S3STORAGE_* settings.
  6. For email, SMS and WhatsApp: turn on your provider (for example PLATFORM_SMTP_ENABLED=true with its settings), put your templates in a folder mounted at /config/notifications (from 0.31.0), and add messages to the key’s _SCOPES. Step by step: Notifications in self-hosted Claspine.
  7. Adding the engine to an app you already have? Your app keeps its code and login; see Add self-hosted Claspine to an existing app for the decisions (database, whose login).
docker-compose.yml for development. In production set SPINE_ENVIRONMENT: PRODUCTION, a real sign-in, your hostnames and TLS.
services:
  spine:
    image: api.claspine.com/claspine/engine:<version>
    ports: ["8080:8080"]
    env_file: spine-engine.env
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/spine
      SPRING_DATASOURCE_USERNAME: spine
      SPRING_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD}
      SPINE_PRODUCT_KEY: app
      SPINE_HOSTS: localhost
      SPINE_ENVIRONMENT: DEVELOPMENT
  postgres:
    image: postgres:16
    environment: { POSTGRES_DB: spine, POSTGRES_USER: spine, POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} }

What goes where in Claspine

Console fieldValue
Your backend (secret)SPINE_API_KEY: the service key (ssk_…), shown once by generate-service-key.
The enginePLATFORM_ENGINE_SERVICEKEYS_0_NAME, _SHA256 and _SCOPES: the key’s digest and what it may do. Optional _HOSTS limits it to your hostnames.

Keep it safe

  • The service key stays on your server. Never send it to a browser or a mobile app.
  • Keep the engine on a private network; only your backend reaches it.
  • Rotate a key without downtime: generate-service-key app-backend --rotate <current sha256> keeps the old key working for seven days.

Claspine stores the values encrypted, never shows them again in full, and never sends them to your app or SDK.

If something goes wrong

docker pull says unauthorized.
Log in first (step 1) with a token that is not revoked; the image version must be inside your update period.
Calls answer 404 HOST_NOT_AVAILABLE.
Send your app’s host: <code>tenantHost</code> in the Node SDK, or the header <code>X-Spine-Host</code>. It must be one of SPINE_HOSTS.
AI answers that no provider is available.
Give the engine at least one provider key (step 5).

← All setup guides