Quickstart

imcore ships as pre-built Linux binary release packages (no source code). This page starts from the package you received and gets a message flowing in about 10 minutes.

0. One-minute trial (Docker Compose)

Want to see it running first? One command boots the full stack (server + PostgreSQL + Redis, schema auto-applied), then try it in the browser with no login:

curl -fsSLO https://balala.im/releases/latest/docker-compose.yml
docker compose up -d
# open http://localhost:8080/home/chat

This is a local-trial config (its secrets are public placeholders — never expose it to the internet). For real deployments, follow the release-package path below.

1. Prerequisites

  • A Linux server (amd64 / arm64 / loong64 — statically linked, no glibc dependency)
  • A database + Redis. PostgreSQL is recommended: the Customer Service edition’s AI/RAG features require PostgreSQL (with the pgvector extension), and read replicas work best on the PG family; existing MySQL infrastructure is fully supported too
  • RabbitMQ or NATS JetStream (cluster deployments only — a single-node trial doesn’t need one)

No Go toolchain, no compiling.

2. Get and unpack the release package

The Basic edition is free; paid editions are delivered with your order (contact sales). Packages are named by edition and architecture:

tar -xzf imcore-basic-<version>-linux-amd64.tar.gz
cd basic

Package layout:

bin/          websocket / persist_consumer / jetstream_consumer / migrate / demo_token …
config/       app.yaml.example (with this edition's recommended settings)
migrations/   database migration SQL
docs/         client integration guide, feature matrix

3. Configure

cp config/app.yaml.example config/app.yaml

At minimum, set the database connection and the Redis address. The database is selected by a single switch — database.driver: postgres | mysql (the template defaults to postgres): fill in the DSN under the matching postgres: / mysql: section and leave the other one alone. bin/migrate and the server read the same switch.

For paid editions, place the license file from your order on the server and point license.file at it (the Basic edition needs no license file).

Default ports: HTTP 8080 (WebSocket embedded on the same port at /acc), gRPC 9001.

4. Initialize the database

./bin/migrate -status    # list pending migrations
./bin/migrate            # apply them (tracked in schema_migrations)

5. Run and verify

./bin/websocket

In another terminal, mint a test JWT with the bundled demo_token tool (pass the value of auth.jwt_secret from your app.yaml), then open a WebSocket:

./bin/demo_token -user alice -secret "<auth.jwt_secret>"
npx wscat -c "ws://localhost:8080/acc?token=<output-from-above>"

In production, your business backend mints client tokens — see the Client Integration Guide for the validation rules (HS256, issuer / audience).

Once connected, send the login and message commands from the Client Integration Guide. In production, proxy /acc via Nginx and run the processes under systemd.