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:
| Deployment | What it runs | Scales on |
|---|---|---|
backend-api | The HTTP API on port 8080, served at /api. | CPU, 2–4 pods |
backend-worker | Background 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 |
frontend | The 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
- Kubernetes: an EKS cluster with the AWS Load Balancer Controller and the metrics-server add-on.
kubectlwith Kustomize (built in). - PostgreSQL: RDS or Aurora PostgreSQL, reachable from the cluster, allowing about 100 connections. AnselIQ is tested on PostgreSQL 18.
- S3: the buckets your file feeds read, in one region.
- TLS: an ACM certificate for the hostname users will open AnselIQ at.
- Images: the
anseliq-backendandanseliq-frontendimages, which you build from source and push to a registry the cluster can pull from, such as ECR. - Optional: KEDA, to scale workers on queue depth, and a GPU or large-CPU node for AI matching.
Default resource requests per pod:
| Pod | CPU request | Memory request / limit |
|---|---|---|
backend-api | 250m | 512 Mi / 1 Gi |
backend-worker | 500m | 1 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:
- JDK 26 and sbt
- Node.js 22, for the web app's build
- Docker, with
buildxif you build on a machine that isn't x86-64 (an Apple Silicon Mac, say)
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.
| Placeholder | Value |
|---|---|
REPLACE_ME_REGISTRY | The DOCKER_REGISTRY you pushed the images to, e.g. <account>.dkr.ecr.<region>.amazonaws.com. |
REPLACE_ME_VERSION | The version you built, e.g. 0.1.2 (without a v). |
REPLACE_ME_RDS_ENDPOINT | The database endpoint. |
REPLACE_ME_AWS_REGION | The region of the feed buckets. |
REPLACE_ME_AWS_ACCOUNT_ID, REPLACE_ME_S3_READ_ROLE | The S3 read role above. |
REPLACE_ME_ACM_CERTIFICATE_ARN | The 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.
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
| Variable | Default | Purpose |
|---|---|---|
DB_HOST, DB_PORT | localhost, 5432 | The PostgreSQL server. |
DB_NAME | recon_db | The database. |
DB_SCHEMA | recon | The schema AnselIQ creates and uses. |
DB_USER, DB_PASSWORD | The database user. | |
DB_MAX_CONNECTIONS | 10 | Connection pool size per pod. Each pod uses up to this plus 2. |
DB_MIGRATE_ON_START | true | Apply schema migrations at start. The Kubernetes install sets it to false and migrates in an init container instead. |
S3_REGION | us-east-1 | The feed buckets' region. |
S3_USERNAME, S3_PASSWORD | A fixed access key and secret. Leave unset to use the pod's IAM role or the AWS default credentials chain. | |
S3_ENDPOINT | An S3-compatible endpoint to use instead of AWS. | |
JWT_SECRET | Required. Signs sign-in tokens; at least 32 bytes. | |
ADMIN_EMAIL, ADMIN_PASSWORD | The first Admin, created at start if there's no active Admin. |
Services
| Variable | Default | Purpose |
|---|---|---|
HTTP_ENABLED | true | Serve the API. |
HTTP_HOST | 0.0.0.0 | The address the API listens on. |
SCHEDULER_ENABLED | true | Queue the periodic jobs: the file scan and the daily reporting snapshot, checked every minute. |
WORKERS_ENABLED | true | Run 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_PORT | 8081 | The health check port. |
SHUTDOWN_DRAIN_TIMEOUT | 25s | How 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=75 | JVM 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).
| Variable | Set to |
|---|---|
MATCH_SUGGESTIONS_ENABLED | true |
MATCH_SUGGESTIONS_ADAPTER | local-llm |
LOCAL_LLM_BASE_URL | The model server's API, e.g. http://ollama.anseliq.svc:11434/v1. Default http://localhost:11434/v1. |
LOCAL_LLM_MODEL | The 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/liveand/health/readyon 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
- Every API request needs a sign-in token signed with
JWT_SECRET. Keep the secret insecrets.env, which is never committed, and rotate it by changing it and restarting the backend; everyone signs in again. - The S3 role can only list and read the feed buckets, and only AnselIQ's service account can assume it.
- The load balancer is internal by default and terminates TLS with your ACM certificate.
- With AI matching on, the model runs in your cluster and transaction data isn't sent anywhere else.