container_cheatsheet.md

Container Cheatsheet

This file explains the challenge container setup in plain language.

What this setup does

• Builds a container image for the API.
• Runs the API as a non-root user inside the container.
• Mounts only the model and cache directories that the container needs.
• Keeps the container filesystem read-only except for temporary memory storage.
• Exposes the API only on 127.0.0.1:<port> on the host, not to the whole network.

Important idea

There are two different places to think about:

• Host: your university server account.
• Container: the isolated process that runs the API.

The API listens on 0.0.0.0:8000 inside the container so Docker can reach it. Docker then publishes that port only to 127.0.0.1:8000 on the host. That means the API is locally reachable on the server, but not globally exposed by default.

Files

• Dockerfile: defines the image.
• compose.yaml: defines how the container runs.
• .env.example: environment template for container settings.
• runtime/models/: place to mount models from by default.
• runtime/cache/: writable cache directory on the host.
• scripts/docker_*.sh: helper commands.

One-time setup

cd /home/alatipov/TEXT2SPARQL_Challenge
cp .env.example .env

If your real model directory is somewhere else, edit .env and change:

HOST_MODEL_DIR=/path/to/your/models

Start Docker for your user

cd /home/alatipov/TEXT2SPARQL_Challenge
./scripts/docker_service_start.sh

The helper scripts automatically use:

DOCKER_HOST=unix:///run/user/1021/docker.sock

Important note about logout / reboot

Right now, Docker is running in rootless user mode for your account. That works without root privileges, but your user does not currently have linger enabled.

Practical meaning:

• While you are logged in, you can start and use Docker normally.
• After a reboot, you will likely need to log in and start the user Docker service again.
• To make it survive reboot without manual login, an administrator would need to run:

sudo loginctl enable-linger alatipov

Build the container

cd /home/alatipov/TEXT2SPARQL_Challenge
./scripts/docker_build.sh

Start the API container

cd /home/alatipov/TEXT2SPARQL_Challenge
./scripts/docker_up.sh

Check that it works

curl "http://127.0.0.1:8000/health"
curl "http://127.0.0.1:8000/text2sparql?dataset=https://text2sparql.aksw.org/2026/dbpedia/&question=Who%20directed%20Inception%3F"

See logs

cd /home/alatipov/TEXT2SPARQL_Challenge
./scripts/docker_logs.sh

Stop the container

cd /home/alatipov/TEXT2SPARQL_Challenge
./scripts/docker_down.sh

What is "active"?

The API is active when the container is running.

You can check:

./scripts/docker_ps.sh

Why this is safer than exposing your whole server

• The container only gets the directories you mount.
• The process inside the container is not root.
• The container cannot write to most of its own filesystem.
• The published API port is only bound to localhost on the host.

What this does not solve

• It does not make the service public by itself.
• It does not replace university policy approval.
• It does not fully sandbox malicious model code.
• It does not protect secrets that you mount into the container yourself.

If you want a public URL later

Recommended order:

1. Run the API container locally on the server.
2. Test it with the organizer client.
3. Add a tunnel or reverse proxy in front of it.
4. Register the resulting public URL.