README

ValkyrAI Launch: Generate, Host, and Run ThorAPI Apps

Overview

Backend endpoints to generate code and host Spring Boot apps on ECS Fargate with EFS and ALB/Route53
Runner Docker image that executes your exec jar from EFS with 2GB heap
Local Docker Desktop harness to run multiple instances without Kubernetes
Minimal React UI to manage instances under /hosting

Backend API

Generate code (existing):
- POST /v1/thorapi/generate (multipart: specification, generator, optional config)
- POST /v1/thorapi/generate/{applicationId}
Hosting endpoints:
- POST /v1/thorapi/host-instance (multipart/form-data)
  - appName: unique name used for service and subdomain
  - jar: Spring Boot executable JAR
  - memoryMb default 2048, cpuUnits default 1024
  - registerGateway: default true (ALB+Route53)
  - env: optional key=value;key2=value2 (e.g., JWT_SECRET=...;THORAPI_SECRET_KEY=...)
- POST /v1/thorapi/host-instances: list instances
- POST /v1/thorapi/host-instance/start|stop|restart: body appName=<...>
- POST /v1/thorapi/host-instance/metrics: CloudWatch CPU/Memory (15m)

AWS Prerequisites

ECR: build/push thorapi-runner image or let ECS pull from your registry
EFS: filesystem + access point mounted to ECS at /efs/apps; same EFS mounted on ValkyrAI server at THORAPI_APPS_ROOT (default /mnt/efs/apps)
ECS: cluster and Fargate-capable task definition thorapi-runner with container port 8080 and EFS volume
ALB/Route53: HTTPS listener (ACM wildcard for *.thorapi.com), listener ARN and hosted zone ID configured

Config keys (application.yaml or env)

THORAPI_APPS_ROOT: where controller writes uploaded JARs (EFS mount path)
THORAPI_ECS_CLUSTER, THORAPI_TASK_DEFINITION, THORAPI_CONTAINER_NAME, THORAPI_CONTAINER_PORT
THORAPI_VPC_ID, THORAPI_SUBNET_IDS, THORAPI_SECURITY_GROUP_IDS, THORAPI_ASSIGN_PUBLIC_IP
THORAPI_ALB_LISTENER_ARN, THORAPI_HOSTED_ZONE_ID, THORAPI_DOMAIN_ROOT

Runner Image

Path: docker/thorapi-runner
Env: RUNNER_APPS_DIR (default /efs/apps), RUNNER_APP_NAME, JAVA_MAX_HEAP (default 2g)
Health: /actuator/health on SERVER_PORT (default 8080)

Local Harness (Docker Desktop) Files

docker/local-harness/docker-compose.yaml: base (Traefik on port 8089)
docker/local-harness/gen-instance-compose.sh: generates per-app compose override
docker/local-harness/prepare-app.sh: stages valkyrai-exec.jar into apps/<app>/
docker/local-harness/harness-up.sh: detect/build jar, stage it, up traefik + per-app service
docker/local-harness/dev-down.sh: stop and remove
Make targets in Makefile

Quick Start

Build your jar or let the harness build it:
- mvn -q -pl valkyrai -am -DskipTests package
Start one instance end-to-end:
- make harness-up APP=app1
- Adds hosts entry if needed: 127.0.0.1 app1.thorapi.local
- Open: http://app1.thorapi.local:8089
Add more:
- make harness-up APP=app2
- http://app2.thorapi.local:8089
Stop:
- make harness-down

Route /hosting in the web app provides simple controls to upload a JAR, provision, and start/stop/restart instances via backend APIs.

Operational Notes

Health check path is /actuator/health; ensure actuator is enabled in your generated app.
Controller writes jars to THORAPI_APPS_ROOT/<app>/valkyrai-exec.jar, which runner executes.
ECS sizing currently uses the task definition; CPU/memory request in API is reserved for future dynamic task def support.
CloudWatch metrics endpoint requires cloudwatch:GetMetricStatistics permissions.

Next Steps (optional)