Quick Start (DevOps)
TL;DR - It is a standard Python / Flask container: install, validate in about 15 minutes
A GenAI-Logic project is a plain Python (Flask, SQLAlchemy) service: one process, one port (5656), configured by environment variables, state in your database. It runs in a standard public image, apilogicserver/api_logic_server; there is nothing to build to try it.
This page is for DevOps teams: install, run, verify, and what to look at. You need Docker or Podman, nothing else - no Python install.
What you are running
| Item | Detail |
|---|---|
| Image | apilogicserver/api_logic_server on Docker Hub, linux amd64 and arm64. Built from docker/api_logic_server.Dockerfile: python:3.12-slim, plus pip install -r requirements.txt |
| Process | One Python process: python3 /app/api_logic_server_run.py (Flask). gunicorn is in the image, for example gunicorn api_logic_server_run:flask_app -w 2 -b 0.0.0.0:5656 |
| User | Non-root (api_logic_server) |
| Port | 5656 (HTTP) |
| Your code | The project folder, mounted at /app (or copied into your own image - see Build Project Image) |
| Config | Environment variables (APILOGICPROJECT_*), e.g. database URI, security on/off, port. See devops/docker-standard-image/env.list and Container Configuration |
| State | In your database. The default is SQLite (a file in the project's database/ folder); set APILOGICPROJECT_SQLALCHEMY_DATABASE_URI for PostgreSQL, MySQL, Oracle or SQL Server (drivers are in the image) |
| Logs | stdout, and logs/als.log in the project folder |
| Business logic | Declarative rules in logic/, executed in-process by the LogicBank library on SQLAlchemy commit. No separate service |
| API | JSON:API (/api/<Table>), OpenAPI/Swagger at /api, Admin UI at /admin-app/index.html |
Extra Python packages are plain pip: put RUN pip install <package> in your project's devops/docker-image/build_image.dockerfile, which extends the standard image.
Validate in 15 minutes
Run these from the Manager directory (these commands are for macOS and Linux shells, zsh or bash; on Windows, use WSL2 or Git Bash). The commands use $CONTAINER_CLI, set to docker or podman (see Install-Express for the one-line setup; Podman notes: Podman).
1. Pull the image
$CONTAINER_CLI pull apilogicserver/api_logic_server
# inventory of every Python package
$CONTAINER_CLI run --rm apilogicserver/api_logic_server pip list
Expect: pulls in a minute or so (about 1 GB); the pip list is the complete software inventory, for your scanning tools.
Behind a corporate registry? If Docker Hub is blocked, mirror the image into yours, then use your name wherever these commands say
apilogicserver/api_logic_server(and inFROMinbuild_image.dockerfile):$CONTAINER_CLI pull apilogicserver/api_logic_server $CONTAINER_CLI tag apilogicserver/api_logic_server <your-registry>/api_logic_server $CONTAINER_CLI push <your-registry>/api_logic_serverThe image is public, built from the Dockerfile linked above, and the server makes no outbound calls at startup. We ran a project in a container with no network (
--network none): the API and Admin UI served normally. Outbound calls happen only for features you configure: Keycloak, the MCP client, n8n, and LLM calls from AI rules. One detail: the Admin UI page loads fonts fromfonts.googleapis.comin the browser; if that is blocked, the browser falls back to its default fonts.
2. Create a project locally (developers do this)
Developers create and test projects with a local install (see Install-Express); DevOps then runs the same project folder in the container. From the Manager (venv active):
genai-logic create \
--project_name=basic_demo \
--db_url=sqlite:///samples/dbs/basic_demo.sqlite
cd basic_demo
# adds the sample rules customer credit check
genai-logic add-cust
cd ..
Expect: a basic_demo folder of ordinary Python files (models, API, rules, tests, devops/). Nothing here needs a container.
No local Python? The container can create the project too:
$CONTAINER_CLI run --rm -v ${PWD}:/localhost apilogicserver/api_logic_server genai-logic create --project_name=/localhost/basic_demo --db_url=basic_demo, then the same with-w /localhost/basic_demo ... genai-logic add-cust.
3. Run it
$CONTAINER_CLI run -d --name basic_demo \
-p 5656:5656 \
-v ${PWD}/basic_demo:/app \
apilogicserver/api_logic_server \
python3 /app/api_logic_server_run.py
$CONTAINER_CLI logs basic_demo
Expect: log ends with Running on http://0.0.0.0:5656. Open the Admin UI at http://localhost:5656/admin-app/index.html (the full path; http://localhost:5656 redirects there, but /admin-app/ alone is a 404), and http://localhost:5656/api for the API (Swagger).
curl --retry 30 --retry-all-errors --retry-delay 2 "http://localhost:5656/api/Customer/?page%5Blimit%5D=1"
4. Verify the business rules are enforced
The sample declares that a customer's balance cannot exceed the credit limit. Violate it through the API:
curl -i -X PATCH http://localhost:5656/api/Customer/1/ -H 'Content-Type: application/vnd.api+json' -d '{"data":{"type":"Customer","id":"1","attributes":{"credit_limit":1}}}'
Expect: HTTP 400 with the rule's message: Customer balance (...) exceeds credit limit (1). The change was rolled back; the rule runs for every caller of the database session, not just this endpoint.
5. Create and run automated tests (optional)
Tests are Behave (standard Python BDD), in test/api_logic_server_behave/. A new project ships only a placeholder feature, so first create tests from the rules. Test creation takes a few minutes, which is why it is optional.
5a. Create the tests. Open the project (basic_demo) in VS Code with an AI coding assistant (Copilot, Claude Code...) and say:
The project's instructions guide the assistant: it writes a test plan (docs/requirements/<name>/test_plan.md) and the feature files and steps. Review them as you would any code.
5b. Run them in the container (the project must be running, as in step 3):
$CONTAINER_CLI exec \
-w /app/test/api_logic_server_behave \
basic_demo \
python behave_run.py --outfile=logs/behave.log
Expect: scenarios passed, 0 failed, exit code 0 - suitable for a CI step. Logs are in test/api_logic_server_behave/logs/.
6. Explore your container
Stop it and start it again. Your data survives, because it lives in your project folder (the mount), not in the container:
$CONTAINER_CLI stop basic_demo
# same container, same command, same data
$CONTAINER_CLI start basic_demo
# basic_demo is Up, port 5656
$CONTAINER_CLI ps
Look inside. Open a shell in the running container:
Then try these (you are user api_logic_server, not root):
# YOUR project: the folder you mounted
ls /app
# the product: api_logic_server_cli/, bin/
ls /home/api_logic_server
# the CLI is installed in /home/api_logic_server/bin
which genai-logic
# Python 3.12 /usr/local/bin/python
python --version
# the key libraries
pip list | grep -i -E "logicbank|safrs|flask|sqlalchemy"
# Debian 11 bullseye, python:3.12-slim
cat /etc/os-release | head -1
# leave the shell the server keeps running
exit
What you see: your app is at /app, the product and its CLI are installed in the image, and nothing else is needed. It is a standard Python container.
Running a
genai-logiccommand inside this container prints a "port 5656 does not appear to be available" warning: the server in the same container is using it. It is harmless.
7. Optional: app + Postgres with compose
The usual multi-container shape: your app (standard image) and a database, on one network, configured by environment variables. Skip this if you did not set up the Postgres container (see the Manager README, "Containers: Podman or Docker"): creating the project below needs it running.
First create a project over the Postgres sample database northwind (from the Manager, venv active):
Then save this as compose-pg.yml in the Manager directory:
services:
postgres: # database: the apilogicserver/postgres sample image
image: docker.io/apilogicserver/postgres:latest
environment:
- POSTGRES_PASSWORD=p
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d northwind"]
interval: 3s
retries: 20
app: # your project, in the standard image
image: docker.io/apilogicserver/api_logic_server:latest
command: python3 /app/api_logic_server_run.py
volumes:
- ./nw_pg:/app
ports:
- "5657:5656" # host 5657, so it does not clash with basic_demo on 5656
environment:
# "postgres" is the service name above, not localhost
- APILOGICPROJECT_SQLALCHEMY_DATABASE_URI=postgresql://postgres:p@postgres/northwind
depends_on:
postgres:
condition: service_healthy
$CONTAINER_CLI compose -f compose-pg.yml up -d
curl --retry 30 --retry-all-errors --retry-delay 2 "http://localhost:5657/api/Customer/?page%5Blimit%5D=1"
$CONTAINER_CLI compose -f compose-pg.yml down
Expect (curl retries for a few seconds while the app starts): a customer (Alfreds Futterkiste, Berlin) read from Postgres, on port 5657. (If you see Alice it came from basic_demo, not Postgres. An error proxy already running means the host port is taken: change the left number in ports.) The environment variable overrides the database URI the project was created with, so one project folder runs unchanged against different databases. The compose file uses no published database port, so it does not clash with a Postgres container you already run.
Podman needs a compose provider (
brew install docker-compose); see Podman.
8. Clean up, and try your own variations
Then, as you wish:
- Your database - add
-e APILOGICPROJECT_SQLALCHEMY_DATABASE_URI=postgresql://user:pw@host/dbto the$CONTAINER_CLI runin step 3. To create a project over an existing database, use--db_url=<that URI>in step 2. - gunicorn - replace the
python3 ...command withgunicorn api_logic_server_run:flask_app -w 2 -b 0.0.0.0:5656(add-w /appto$CONTAINER_CLI run). - Your own image -
sh devops/docker-image/build_image.sh ., thensh devops/docker-image/run_image.sh. The dockerfile is 3 lines:FROM apilogicserver/api_logic_server,COPY,CMD. See Build Project Image. Projects created before release 17.05.37 carry older scripts that calldockerand need adev-network. On Podman, build directly instead:$CONTAINER_CLI build -f devops/docker-image/build_image.dockerfile -t myproject .(run from the project folder), then run it as in step 3 withmyprojectas the image. - Compose -
$CONTAINER_CLI compose -f devops/docker-standard-image/docker-compose-standard-image.yml up - Security -
genai-logic add-auth --provider-type=sql(run as in step 2, with-w /localhost) uses a SQL user table - no other container. Keycloak is also supported; see Security.
What to look at
For a DevOps review, these are the places to look:
- The Dockerfile and requirements.txt - the full dependency list (Flask, SQLAlchemy, SAFRS, LogicBank, DB drivers).
- The project's
api_logic_server_run.pyandconfig/config.py- how the app starts and how environment variables override settings. logic/- the business rules are readable Python; they are source code, in your repository, reviewed and versioned like any other.devops/- the container and deployment files the project carries: Use Standard Image, Build Project Image, Run Container, cloud deployment (Azure), and Podman.
Known limits
- The image runs the Flask server by default (it logs a "development server" warning); use gunicorn, as above, for production.
- The sample steps above use SQLite, which suits validation. For production, use a server database via the environment variable.
- Container networking: a container reaches another container (database, Keycloak) by its network name, not
localhost. Create a network ($CONTAINER_CLI network create dev-network) and add--net dev-networkto the$CONTAINER_CLI run.