Quick start

Stand up io.sign locally for evaluation with Docker Compose

Use Docker Compose to run the io.sign backend on one machine, with its PostgreSQL database and Redis, so you can explore the API before you plan a real deployment.

🚧

For evaluation only. This single-host Compose setup disables authentication and runs every API component in one container alongside PostgreSQL and Redis. Don't use it in production. For a real deployment, see Deployment options and Configuration.

Prerequisites

  • Docker and the Docker Compose plugin (docker compose version ≥ v2).
  • Access to the io.finnet container registry. Ask your io.finnet contact for the registry URL, the io.sign API and migrations image names, the tag matching your evaluation, and pull credentials.
  • (Optional) A licence key issued by io.finnet. Without one, io.sign starts in read-only mode: you can explore the API, but it rejects write operations.

Authenticate to the registry once:

docker login <registry>

Step 1: Create an environment file

Create a file named .env next to the Compose file below. These values wire the containers together and are safe for local evaluation:

# --- io.finnet image registry (fill these in) ---
IOSIGN_REGISTRY=<registry>
IOSIGN_API_IMAGE=<api-image>
IOSIGN_MIGRATIONS_IMAGE=<migrations-image>
IOSIGN_VERSION=<tag>

# --- Runtime ---
NODE_ENV=production
STAGE=local
ENV=local

# --- Components (run everything in one container for evaluation) ---
ENABLE_ORPC=true
ENABLE_GRPC=true
ENABLE_GRPC_STREAM=true
ENABLE_ORCHESTRATOR=true
ENABLE_CRON_TASKS=true
ENABLE_REDIS=true

# --- Ports ---
API_PORT=3000
GRPC_PORT=50051

# --- Database ---
DB_NAME=io_sign
DB_USER=io_sign
DB_PASSWORD=io_sign

# --- Auth: disabled for local evaluation only ---
# In any real deployment set JWT_ENABLED=true and configure JWT_PROVIDERS.
JWT_ENABLED=false

# --- Licence (optional for evaluation; omit to run in read-only mode) ---
# LICENSE_KEY=<base64-license-issued-by-iofinnet>

# --- Logging ---
LOG_LEVEL=info
LOG_PRETTY=true

Step 2: Create the Compose file

Save this as docker-compose.yml:

name: io-sign-quickstart

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER} -d ${DB_NAME}"]
      interval: 5s
      timeout: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 10

  migrations:
    image: ${IOSIGN_REGISTRY}/${IOSIGN_MIGRATIONS_IMAGE}:${IOSIGN_VERSION}
    env_file: .env
    environment:
      DB_HOST: postgres
    depends_on:
      postgres:
        condition: service_healthy

  api:
    image: ${IOSIGN_REGISTRY}/${IOSIGN_API_IMAGE}:${IOSIGN_VERSION}
    env_file: .env
    environment:
      DB_HOST: postgres
      REDIS_HOST: redis
    ports:
      - "127.0.0.1:${API_PORT}:${API_PORT}"
      - "127.0.0.1:${GRPC_PORT}:${GRPC_PORT}"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
      migrations:
        condition: service_completed_successfully

volumes:
  postgres_data:
  redis_data:

The migrations service is a one-shot container: it applies the database schema and exits before the api service starts.

Step 3: Start io.sign

docker compose config --quiet
docker compose up

Compose pulls the images, starts PostgreSQL and Redis, runs migrations, then launches the API. The service is ready when the logs show the REST and gRPC servers listening on ports 3000 and 50051.

Step 4: Verify

In another terminal:

curl --fail-with-body http://localhost:3000/v2/health/check
curl --fail-with-body --http2-prior-knowledge http://localhost:50051/health

Both return 200 with JSON reporting a healthy service. Check that the REST response isn't HTML: an unmatched path returns the API playground with status 200. The gRPC listener requires HTTP/2, so use a curl build with HTTP/2 support (check curl --version). Then open the interactive API playground in your browser:

http://localhost:3000/

The OpenAPI spec is served at http://localhost:3000/spec.json.

Step 5: Continue to signing or stop the evaluation

To register signers, create a vault, and produce a signature, follow the io.sign overview. A healthy API alone does not demonstrate a working signing ceremony.

To stop this evaluation:

docker compose down        # stop containers, keep data
docker compose down -v      # stop and delete the database and Redis volumes

Next steps

This evaluation setup leaves out what you need for end-to-end signing:

  • Authentication. Turn it on with JWT_ENABLED=true and point JWT_PROVIDERS at your identity provider. See Authentication.
  • A licence. Set LICENSE_KEY to leave read-only mode. See Licensing.
  • An MQTT broker and signers. A full signing ceremony needs an EMQX broker and signers: Virtual Signers, Mobile Signers, or both. See MQTT broker.

When you're ready to run io.sign in production, continue to Deployment options and Configuration.


Did this page help you?