Skip to content

Installation & operations

Installing and running AnselIQ

AnselIQ runs inside your own environment, so transaction data never leaves your network. This guide installs it on Kubernetes in your AWS account (Amazon EKS, RDS and S3) and covers running it afterwards.

Architecture

An install runs three deployments behind one Ingress:

DeploymentWhat it runsScales on
backend-apiThe HTTP API on port 8080, served at /api.CPU, 2–4 pods
backend-workerBackground jobs (file scans, ingestion, reconciliation, reporting snapshots, AI suggestions) and the scheduler that queues the periodic ones.CPU, or queued jobs with KEDA, 1–4 pods
frontendThe web app, as static files served by nginx.Fixed at 2 pods

Both backend deployments run the same image with different services switched on. All state lives in PostgreSQL, including the job queue, so any number of replicas is safe: each job is claimed by one worker, and a job whose worker dies is picked up by another and resumes from its last checkpoint. AnselIQ reads feed files from S3 and, if AI matching is on, calls a model served inside the cluster.

Requirements

Default resource requests per pod:

PodCPU requestMemory request / limit
backend-api250m512 Mi / 1 Gi
backend-worker500m1 Gi / 2 Gi

Workers need more memory because reconciliation holds each pass's matching groups in memory.

Building the images

AnselIQ is distributed as source code, so you build its two images yourself and push them to your own registry. You need:

In ECR, create two repositories named anseliq-backend and anseliq-frontend, and sign Docker in to the registry. Then build and push a release:

git clone https://github.com/eweise/anseliq.git
cd anseliq
git checkout v0.1.2                  # the release to build

export DOCKER_REGISTRY=<account>.dkr.ecr.<region>.amazonaws.com
export DOCKER_PLATFORM=linux/amd64   # match your cluster's nodes
sbt "backend/Docker/publish; frontend/Docker/publish"

This pushes anseliq-backend:0.1.2 and anseliq-frontend:0.1.2. The tag is the release version, read from the git tag you checked out. A build from any other commit gets a version like 0.1.2-4-abcd1234. JAVA_HOME must point at JDK 26.

Preparing AWS

Database

Create an empty database and a user that owns it. AnselIQ creates its recon schema and everything in it the first time it starts, so nothing else needs running by hand.

CREATE USER anseliq WITH PASSWORD '...';
CREATE DATABASE recon_db OWNER anseliq;

RDS requires TLS by default, and AnselIQ uses it when the server asks for it.

S3 access

AnselIQ reads S3 with an IAM role that only its service account can assume (IAM Roles for Service Accounts). It needs only to list and read the feed buckets:

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::<feed-bucket>" },
    { "Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::<feed-bucket>/*" }
  ]
}

Its trust policy, with your cluster's OIDC provider:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::<account>:oidc-provider/<oidc-provider>" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": { "<oidc-provider>:sub": "system:serviceaccount:anseliq:anseliq-backend" }
    }
  }]
}

Installing

AnselIQ ships as a Kustomize overlay for EKS. Copy it for your install and replace every REPLACE_ME_ value; grep -rn REPLACE_ME . lists what's left.

PlaceholderValue
REPLACE_ME_REGISTRYThe DOCKER_REGISTRY you pushed the images to, e.g. <account>.dkr.ecr.<region>.amazonaws.com.
REPLACE_ME_VERSIONThe version you built, e.g. 0.1.2 (without a v).
REPLACE_ME_RDS_ENDPOINTThe database endpoint.
REPLACE_ME_AWS_REGIONThe region of the feed buckets.
REPLACE_ME_AWS_ACCOUNT_ID, REPLACE_ME_S3_READ_ROLEThe S3 read role above.
REPLACE_ME_ACM_CERTIFICATE_ARNThe certificate for AnselIQ's hostname.

Then create secrets.env from secrets.env.example:

# The application's database user
DB_USER=anseliq
DB_PASSWORD=...
# Signs sign-in tokens. At least 32 bytes: openssl rand -base64 48
JWT_SECRET=...
# The first Admin, created on first start when there's none; ignored after that.
ADMIN_EMAIL=you@example.com
ADMIN_PASSWORD=...   # at least 8 characters

Apply it:

kubectl apply -k .
kubectl -n anseliq get pods        # wait for every pod to be Ready
kubectl -n anseliq get ingress     # the load balancer's address

Point your hostname's DNS at the load balancer, then sign in as ADMIN_EMAIL and create the other users under Admin → Users.

The load balancer is internal, reachable only from your network. If users reach AnselIQ over the internet, change scheme in ingress-alb.yaml to internet-facing.

Configuration reference

The backend is configured with environment variables, set in the overlay's anseliq-config ConfigMap or, for secrets, in secrets.env.

Database, S3 and sign-in

VariableDefaultPurpose
DB_HOST, DB_PORTlocalhost, 5432The PostgreSQL server.
DB_NAMErecon_dbThe database.
DB_SCHEMAreconThe schema AnselIQ creates and uses.
DB_USER, DB_PASSWORDThe database user.
DB_MAX_CONNECTIONS10Connection pool size per pod. Each pod uses up to this plus 2.
DB_MIGRATE_ON_STARTtrueApply schema migrations at start. The Kubernetes install sets it to false and migrates in an init container instead.
S3_REGIONus-east-1The feed buckets' region.
S3_USERNAME, S3_PASSWORDA fixed access key and secret. Leave unset to use the pod's IAM role or the AWS default credentials chain.
S3_ENDPOINTAn S3-compatible endpoint to use instead of AWS.
JWT_SECRETRequired. Signs sign-in tokens; at least 32 bytes.
ADMIN_EMAIL, ADMIN_PASSWORDThe first Admin, created at start if there's no active Admin.

Services

VariableDefaultPurpose
HTTP_ENABLEDtrueServe the API.
HTTP_HOST0.0.0.0The address the API listens on.
SCHEDULER_ENABLEDtrueQueue the periodic jobs: the file scan and the daily reporting snapshot, checked every minute.
WORKERS_ENABLEDtrueRun background jobs. Each kind can be switched separately with WORKER_INGESTION_ENABLED, WORKER_RECONCILIATION_ENABLED, WORKER_CREATE_FILE_INVENTORY_ENABLED, WORKER_GENERATE_RECON_STATS_ENABLED and WORKER_SUGGEST_MATCHES_ENABLED.
HEALTH_PORT8081The health check port.
SHUTDOWN_DRAIN_TIMEOUT25sHow long running jobs get to finish on shutdown before they're handed back to the queue. Keep it under the pod's termination grace period.
JAVA_OPTS-XX:MaxRAMPercentage=75JVM options.

Turning on AI matching

AI match suggestions are off by default. They use a language model served inside your cluster through an OpenAI-compatible chat completions API that supports structured (JSON schema) output, such as Ollama. No outside AI service is called. The default model is qwen2.5:7b (about 4.7 GB).

VariableSet to
MATCH_SUGGESTIONS_ENABLEDtrue
MATCH_SUGGESTIONS_ADAPTERlocal-llm
LOCAL_LLM_BASE_URLThe model server's API, e.g. http://ollama.anseliq.svc:11434/v1. Default http://localhost:11434/v1.
LOCAL_LLM_MODELThe model name. Default qwen2.5:7b.

Set them on the backend-worker deployment. After each reconciliation, a suggestion job asks the model about the movements left unmatched; suggestions then wait for a person to review them.

Scaling

The backend scales itself on CPU between 2 and 4 API pods and 1 and 4 worker pods, using metrics-server. At the maximum, the pods hold about 100 database connections, so raise maxReplicas in base/autoscaling.yaml only together with the database's max_connections.

With KEDA installed, workers can scale on how many jobs are queued or running instead, which tracks their load better than CPU. Add the component to the overlay's kustomization.yaml and point it at your database:

components:
  - ../../components/worker-queue-autoscaling

patches:
  # ...the existing patches, then:
  - target:
      kind: ScaledObject
      name: backend-worker
    patch: |-
      - op: replace
        path: /spec/triggers/0/metadata/host
        value: <the RDS endpoint>
      - op: replace
        path: /spec/triggers/0/metadata/userName
        value: <DB_USER from secrets.env>

Upgrading

Build and push the new release, change both image newTags in kustomization.yaml to its version, and run kubectl apply -k . again. Each backend pod applies any pending database migrations before it starts, and running jobs drain (or go back to the queue) before old pods stop. If you keep your overlay in your own repository, you can reference the base at a release tag instead of copying it.

Health, logs and backups

Health checks
Every backend pod serves /health/live and /health/ready on port 8081, which the Kubernetes probes use.
Logs
The backend logs JSON to standard output, ready for CloudWatch or any log collector. It logs its version when it starts.
Background work
The Jobs page shows every job's status, attempts and errors. Failed jobs are retried with an increasing delay before they're marked as an error.
Backups
The database holds everything AnselIQ knows: configuration, the ledger, reconciliations and exceptions. Back it up with RDS automated backups or snapshots. Feed files stay in your S3 buckets and are only read.

Security notes