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=trueStep 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 upCompose 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/healthBoth 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 volumesNext steps
This evaluation setup leaves out what you need for end-to-end signing:
- Authentication. Turn it on with
JWT_ENABLED=trueand pointJWT_PROVIDERSat your identity provider. See Authentication. - A licence. Set
LICENSE_KEYto 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.
Updated 17 days ago