Your project runs on your laptop with make up and Docker. HackerRank cannot run Docker. This guide shows what to add so the same project runs there. Your application code stays exactly as it is.
Six steps. The files in step 1 are the exact ones in the project we returned to you, so you can copy them as they are.
A HackerRank machine is itself a container without admin rights, so Docker cannot start inside it. The 8 containers become 8 ordinary processes on that one machine.
docker-compose.yml starts 8 containershackerrank/setup.sh starts 8 processes on one machineThis works without touching the app because the app already reads every host name and URL from an environment variable (common/config.py). Docker used to supply those values. On HackerRank, one small file supplies them.
One file at the project root and one new folder. Nothing existing is edited in this step.
Also add these five lines to .gitignore, so the files the setup creates stay out of git: .venv/, .cache/, .run/, logs/, test-results/.
Open a file to see what it does, where its contents come from in your Docker setup, and the full text to copy.
make up, Test runs make test. It names the scoring command and opens port 8000 in the preview pane.docker-compose.yml.version: 1.0
configuration:
has_webserver: true
scoring:
command: bash hackerrank/score.sh
files:
- test-results/junit.xml
readonly_paths:
- hackerrank/**
- Makefile
ide_config:
default_open_files:
- README.md
project_menu:
install: bash hackerrank/setup.sh
run: make up
test: make test
ports_settings:
"8000":
name: Admin UI
hidePreview: false
primary: true127.0.0.1.environment: values in docker-compose.yml. Container names such as mysql, redis and kafka become 127.0.0.1.MYSQL_HOST=127.0.0.1
MYSQL_USER=root
MYSQL_PASSWORD=root
MYSQL_DB=policy
REDIS_HOST=127.0.0.1
KAFKA_BOOTSTRAP=127.0.0.1:9092
POLICY_API_URL=http://127.0.0.1:8003
IDENTITY_JWKS_URL=http://127.0.0.1:8004/.well-known/jwks.json
ADMIN_URL=http://127.0.0.1:8002
POLICY_URL=http://127.0.0.1:8003
IDENTITY_URL=http://127.0.0.1:8004
KEY_DIR=${HOME}/.local/share/policy-engine/keys
ALLOW_TTL_OVERRIDE=1
PYTHONUNBUFFERED=1mysql, redis and kafka services in docker-compose.yml: MySQL 8.0, Redis 7 and Kafka 3.7.0, with the same passwords and ports.#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
ROOT="$(pwd)"
STATE_DIR="${POLICY_ENGINE_STATE_DIR:-$HOME/.local/share/policy-engine}"
KAFKA_VERSION="3.7.0"
KAFKA_SCALA="2.13"
KAFKA_HOME="$STATE_DIR/kafka_${KAFKA_SCALA}-${KAFKA_VERSION}"
KAFKA_DATA="$STATE_DIR/kafka-data"
KAFKA_CONFIG="$STATE_DIR/kafka-server.properties"
KAFKA_TOPIC="policy.changes"
MYSQL_DATA="$STATE_DIR/mysql-data"
MYSQL_SOCKET="$STATE_DIR/mysqld.sock"
MYSQL_ROOT_PASSWORD="root"
MYSQL_DATABASE="policy"
info() { echo -e "\033[0;32m[infra]\033[0m $1"; }
warn() { echo -e "\033[1;33m[infra]\033[0m $1"; }
fail() { echo -e "\033[0;31m[infra]\033[0m $1" >&2; exit 1; }
port_open() { (echo > "/dev/tcp/127.0.0.1/$1") >/dev/null 2>&1; }
wait_port() {
local port="$1" name="$2" timeout="${3:-60}"
for _ in $(seq 1 "$timeout"); do
port_open "$port" && return 0
sleep 1
done
fail "$name did not open port $port within ${timeout}s"
}
as_root() {
if [ "$(id -u)" -eq 0 ]; then "$@"; else sudo -n "$@"; fi
}
wait_for_apt() {
local waited=0
while pgrep -x apt-get >/dev/null 2>&1 || pgrep -x apt >/dev/null 2>&1 || pgrep -x dpkg >/dev/null 2>&1 ||
pgrep -f "unattended-upgrade( |$)" >/dev/null 2>&1; do
[ "$waited" -eq 0 ] && warn "Another apt/dpkg process is running; waiting for it to finish..."
[ "$waited" -ge 600 ] && fail "apt is still locked after ${waited}s"
sleep 5
waited=$((waited + 5))
done
return 0
}
apt_get() {
as_root env DEBIAN_FRONTEND=noninteractive apt-get -o DPkg::Lock::Timeout=600 "$@"
}
mysql_root() {
mysql --no-defaults -uroot -p"$MYSQL_ROOT_PASSWORD" --socket="$MYSQL_SOCKET" "$@" 2>/dev/null
}
install_packages() {
local missing=()
command -v mysqld >/dev/null 2>&1 || missing+=(mysql-server-core-8.0)
command -v mysql >/dev/null 2>&1 || missing+=(mysql-client-core-8.0)
command -v redis-server >/dev/null 2>&1 || missing+=(redis-server)
command -v java >/dev/null 2>&1 || missing+=(openjdk-21-jre-headless)
command -v socat >/dev/null 2>&1 || missing+=(socat)
command -v make >/dev/null 2>&1 || missing+=(make)
command -v curl >/dev/null 2>&1 || missing+=(curl)
if [ "${#missing[@]}" -eq 0 ]; then
info "MySQL, Redis, Java, socat and make already installed"
else
info "Installing ${missing[*]} (apt)..."
wait_for_apt
apt_get update -qq || warn "apt-get update reported errors (often an unrelated third-party source); continuing"
apt_get install -y -qq --no-install-recommends "${missing[@]}" >/dev/null
fi
if [ ! -x "$KAFKA_HOME/bin/kafka-server-start.sh" ]; then
local archive="kafka_${KAFKA_SCALA}-${KAFKA_VERSION}.tgz" tmp
tmp="$(mktemp -d)"
mkdir -p "$STATE_DIR"
info "Downloading Kafka $KAFKA_VERSION..."
curl -fsSL --retry 3 -o "$tmp/$archive" "https://archive.apache.org/dist/kafka/$KAFKA_VERSION/$archive" \
|| curl -fsSL --retry 3 -o "$tmp/$archive" "https://dlcdn.apache.org/kafka/$KAFKA_VERSION/$archive" \
|| fail "could not download Kafka $KAFKA_VERSION"
tar -xzf "$tmp/$archive" -C "$STATE_DIR"
rm -rf "$tmp"
fi
}
mysql_first_init() {
info "Initialising MySQL (root password, schema.sql, readonly.sql)..."
mysql --no-defaults -uroot --socket="$MYSQL_SOCKET" <<SQL
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '$MYSQL_ROOT_PASSWORD';
CREATE USER IF NOT EXISTS 'root'@'%' IDENTIFIED WITH mysql_native_password BY '$MYSQL_ROOT_PASSWORD';
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION;
FLUSH PRIVILEGES;
SQL
load_schema
touch "$MYSQL_DATA/.initdb-done"
}
load_schema() {
mysql_root -e "CREATE DATABASE IF NOT EXISTS \`$MYSQL_DATABASE\`"
mysql_root "$MYSQL_DATABASE" < "$ROOT/seed/schema.sql"
mysql_root "$MYSQL_DATABASE" < "$ROOT/seed/readonly.sql"
}
mysql_up() {
mkdir -p "$STATE_DIR"
if ! port_open 3306; then
if [ ! -d "$MYSQL_DATA/mysql" ]; then
rm -rf "$MYSQL_DATA"
mysqld --no-defaults --initialize-insecure --datadir="$MYSQL_DATA" \
--log-error="$STATE_DIR/mysql-init.log" || fail "MySQL initialise failed; see $STATE_DIR/mysql-init.log"
fi
info "Starting MySQL..."
setsid nohup mysqld --no-defaults --datadir="$MYSQL_DATA" --socket="$MYSQL_SOCKET" --port=3306 \
--bind-address=127.0.0.1 --pid-file="$STATE_DIR/mysqld.pid" --log-error="$STATE_DIR/mysql.log" \
--mysqlx=OFF --secure-file-priv=NULL --default-authentication-plugin=mysql_native_password \
--max-connections=500 >/dev/null 2>&1 < /dev/null &
wait_port 3306 MySQL 90
fi
[ -f "$MYSQL_DATA/.initdb-done" ] || mysql_first_init
info "MySQL ready on 3306 (database $MYSQL_DATABASE, root/$MYSQL_ROOT_PASSWORD)"
}
redis_up() {
if ! port_open 6379; then
info "Starting Redis..."
redis-server --daemonize yes --bind 127.0.0.1 --port 6379 --save "" --appendonly no >/dev/null
wait_port 6379 Redis 20
fi
info "Redis ready on 6379"
}
kafka_up() {
if ! port_open 9092; then
mkdir -p "$KAFKA_DATA"
sed "s#^log.dirs=.*#log.dirs=$KAFKA_DATA#" "$KAFKA_HOME/config/kraft/server.properties" > "$KAFKA_CONFIG"
printf 'group.initial.rebalance.delay.ms=0\nauto.create.topics.enable=true\nnum.partitions=1\n' >> "$KAFKA_CONFIG"
if [ ! -f "$KAFKA_DATA/meta.properties" ]; then
info "Formatting Kafka storage (KRaft, single node)..."
"$KAFKA_HOME/bin/kafka-storage.sh" format -t "$("$KAFKA_HOME/bin/kafka-storage.sh" random-uuid)" \
-c "$KAFKA_CONFIG" >/dev/null
fi
info "Starting Kafka $KAFKA_VERSION..."
KAFKA_HEAP_OPTS="-Xms256m -Xmx512m" LOG_DIR="$STATE_DIR/kafka-logs" \
"$KAFKA_HOME/bin/kafka-server-start.sh" -daemon "$KAFKA_CONFIG"
wait_port 9092 Kafka 90
fi
"$KAFKA_HOME/bin/kafka-topics.sh" --bootstrap-server 127.0.0.1:9092 --create --if-not-exists \
--topic "$KAFKA_TOPIC" --partitions 1 --replication-factor 1 >/dev/null
info "Kafka ready on 9092 (topic $KAFKA_TOPIC)"
}
kafka_stop() {
if port_open 9092; then
"$KAFKA_HOME/bin/kafka-server-stop.sh" >/dev/null 2>&1 || true
for _ in $(seq 1 30); do port_open 9092 || break; sleep 1; done
fi
}
reset_data() {
info "Wiping MySQL, Redis and Kafka data and the signing key..."
mysql_up
mysql_root -e "DROP DATABASE IF EXISTS \`$MYSQL_DATABASE\`"
load_schema
redis_up
redis-cli -p 6379 FLUSHALL >/dev/null
kafka_stop
rm -rf "$KAFKA_DATA"
kafka_up
rm -rf "${KEY_DIR:-$STATE_DIR/keys}"
}
infra_down() {
kafka_stop
redis-cli -p 6379 shutdown nosave >/dev/null 2>&1 || true
mysqladmin --no-defaults -uroot -p"$MYSQL_ROOT_PASSWORD" --socket="$MYSQL_SOCKET" shutdown >/dev/null 2>&1 || true
info "MySQL, Redis and Kafka stopped"
}
infra_status() {
for pair in "MySQL:3306" "Redis:6379" "Kafka:9092"; do
if port_open "${pair#*:}"; then echo "${pair%%:*} up (${pair#*:})"; else echo "${pair%%:*} down (${pair#*:})"; fi
done
}
case "${1:-}" in
install) install_packages ;;
up) mysql_up; redis_up; kafka_up ;;
reset) reset_data ;;
down) infra_down ;;
status) infra_status ;;
*) echo "usage: $0 install|up|reset|down|status" >&2; exit 2 ;;
esacinfra.sh, creates a Python 3.11 environment, installs requirements.txt, seeds the demo data and starts the services.Dockerfile (Python version, pip install) and the seed service in docker-compose.yml.#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
ROOT="$(pwd)"
info() { echo -e "\033[0;32m[setup]\033[0m $1"; }
fail() { echo -e "\033[0;31m[setup]\033[0m $1" >&2; exit 1; }
start_ts=$(date +%s)
set -a
. "$ROOT/hackerrank/env"
set +a
export PYTHONPATH="$ROOT"
bash hackerrank/infra.sh install
bash hackerrank/infra.sh up
command -v uv >/dev/null 2>&1 || fail "uv is required (it ships with the HackerRank Python image)"
export UV_CACHE_DIR="${UV_CACHE_DIR:-$ROOT/.cache/uv}"
if [ ! -x .venv/bin/python ]; then
info "Creating the Python 3.11 environment (.venv)..."
uv venv -q --python 3.11 .venv
fi
info "Installing requirements.txt..."
uv pip install -q --python .venv/bin/python -r requirements.txt
info "Seeding demo data (skipped if already seeded)..."
.venv/bin/python -m seed.seed
bash hackerrank/services.sh start
info "Ready in $(( $(date +%s) - start_ts ))s"
echo " Admin UI http://localhost:8002/admin (preview pane: port 8000)"
echo " admin-api http://localhost:8002"
echo " policy-api http://localhost:8003"
echo " identity-api http://localhost:8004"
echo " Next: curl -s localhost:8002/health"admin-api, policy-api, identity-api and the worker. It also forwards port 8000 to 8002 so the admin page shows in the preview pane.command: line of each app service in docker-compose.yml. The list is at the top of the file, in SERVICES.#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
ROOT="$(pwd)"
RUN_DIR="$ROOT/.run"
LOG_DIR="$ROOT/logs"
set -a
. "$ROOT/hackerrank/env"
set +a
export PYTHONPATH="$ROOT"
SERVICES=(
"identity-api|.venv/bin/uvicorn identity_api.main:app --host 0.0.0.0 --port 8004 --workers 1|http://127.0.0.1:8004/health"
"admin-api|.venv/bin/uvicorn admin_api.main:app --host 0.0.0.0 --port 8002 --workers 2|http://127.0.0.1:8002/health"
"policy-api|.venv/bin/uvicorn policy_api.main:app --host 0.0.0.0 --port 8003 --workers 4|http://127.0.0.1:8003/health"
"worker|.venv/bin/python -m worker.consumer|log:worker started"
"admin-preview|socat TCP-LISTEN:8000,fork,reuseaddr TCP:127.0.0.1:8002|port:8000"
)
info() { echo -e "\033[0;32m[services]\033[0m $1"; }
fail() { echo -e "\033[0;31m[services]\033[0m $1" >&2; exit 1; }
running() {
local pid_file="$RUN_DIR/$1.pid"
[ -f "$pid_file" ] && kill -0 "$(cat "$pid_file")" 2>/dev/null
}
ready() {
local name="$1" check="$2"
case "$check" in
log:*) grep -q "${check#log:}" "$LOG_DIR/$name.log" 2>/dev/null ;;
port:*) (echo > "/dev/tcp/127.0.0.1/${check#port:}") >/dev/null 2>&1 ;;
*) curl -fs -o /dev/null "$check" ;;
esac
}
start_one() {
local name="$1" command="$2" check="$3"
if running "$name"; then
info "$name already running (pid $(cat "$RUN_DIR/$name.pid"))"
return 0
fi
setsid nohup $command >"$LOG_DIR/$name.log" 2>&1 < /dev/null &
echo $! > "$RUN_DIR/$name.pid"
for _ in $(seq 1 90); do
ready "$name" "$check" && { info "$name ready (pid $(cat "$RUN_DIR/$name.pid"))"; return 0; }
running "$name" || fail "$name exited; see logs/$name.log"
sleep 1
done
fail "$name was not ready within 90s; see logs/$name.log"
}
stop_one() {
local name="$1" pid_file="$RUN_DIR/$1.pid"
if running "$name"; then
local pid
pid="$(cat "$pid_file")"
kill -- "-$pid" 2>/dev/null || kill "$pid" 2>/dev/null || true
for _ in $(seq 1 15); do
kill -0 "$pid" 2>/dev/null || break
sleep 1
done
info "$name stopped"
fi
rm -f "$pid_file"
}
mkdir -p "$RUN_DIR" "$LOG_DIR"
case "${1:-}" in
start)
[ -x .venv/bin/python ] || fail ".venv is missing; run 'make up' first"
for entry in "${SERVICES[@]}"; do
IFS='|' read -r name command check <<< "$entry"
start_one "$name" "$command" "$check"
done ;;
stop)
for (( i=${#SERVICES[@]}-1; i>=0; i-- )); do
IFS='|' read -r name _ <<< "${SERVICES[$i]}"
stop_one "$name"
done ;;
restart)
bash "$0" stop
bash "$0" start ;;
status)
for entry in "${SERVICES[@]}"; do
IFS='|' read -r name _ <<< "$entry"
if running "$name"; then echo "$name running (pid $(cat "$RUN_DIR/$name.pid"))"; else echo "$name stopped"; fi
done ;;
*) echo "usage: $0 start|stop|restart|status" >&2; exit 2 ;;
esacpytest tests/public, and writes test-results/junit.xml. HackerRank reads the score from that file.make test target in your Makefile.#!/usr/bin/env bash
set -uo pipefail
cd "$(dirname "$0")/.."
ROOT="$(pwd)"
bash hackerrank/setup.sh || exit 1
set -a
. "$ROOT/hackerrank/env"
set +a
export PYTHONPATH="$ROOT"
mkdir -p test-results
.venv/bin/python -m pytest tests/public -q -p no:cacheprovider --junitxml=test-results/junit.xml
exit 0make targets candidates already know (up, test, restart, reset, logs, token), without Docker. It takes the place of Makefile in the HackerRank zip.Makefile. Each docker compose exec ... line becomes a direct command.SHELL := /bin/bash
ENV := set -a; . hackerrank/env; set +a; export PYTHONPATH=$(CURDIR);
PY := .venv/bin/python
up: ## install what is missing, start everything, wait until healthy
@bash hackerrank/setup.sh
down:
@bash hackerrank/services.sh stop; bash hackerrank/infra.sh down
reset: ## wipe all data (MySQL, Kafka, Redis) and start fresh
@bash hackerrank/services.sh stop
@$(ENV) bash hackerrank/infra.sh reset
@bash hackerrank/setup.sh
restart: ## restart the services after a code change
@bash hackerrank/services.sh restart
status:
@bash hackerrank/infra.sh status; bash hackerrank/services.sh status
logs:
@tail -n 20 -F logs/admin-api.log logs/policy-api.log logs/identity-api.log logs/worker.log
test: ## tests you can see
@$(ENV) $(PY) -m pytest tests/public -q
seed-large: ## load the big dataset (5000 rules, 2000 users) for performance work
@$(ENV) $(PY) -m seed.seed --profile large --force
seed-small: ## go back to the small demo dataset
@$(ENV) $(PY) -m seed.seed --profile small --force
loadtest: ## performance check for GET /users/{id}/policy (loads the large dataset first)
@$(ENV) $(PY) -m tests.loadtest
token: ## print a JWT for a user: make token USER=2
@$(ENV) $(PY) -m tests.get_token $(USER)
mysql:
@mysql -h127.0.0.1 -uroot -proot policy
redis:
@redis-cliThe seven files already match the project as you sent it. Check this table whenever you change the Docker setup later.
| If you change this | Update this | Example |
|---|---|---|
An environment: value in docker-compose.yml | hackerrank/env | A new FEATURE_X=1 goes in both places |
A target in Makefile | hackerrank/Makefile | A new make seed-medium |
| An app service, its start command or its port | SERVICES at the top of hackerrank/services.sh | policy-api moves to 6 workers |
| A database, cache or queue container | hackerrank/infra.sh | A new Kafka topic or a MySQL setting |
A package in requirements.txt | Nothing | Setup installs from requirements.txt |
Application code, tests, seed/schema.sql | Nothing | They are used as they are |
Three small wording edits in the docs candidates read. No code.
| File | Edit |
|---|---|
README.md | Add one line: “On HackerRank, open the admin page and the database explorer from the preview pane (port 8000, which forwards to 8002).” |
docs/candidate/README.md | Add the same line. Say that MySQL, Redis and Kafka run as local processes on HackerRank, and that make up already ran when the IDE opened. |
docs/API.md | ALLOW_TTL_OVERRIDE=1 is “set in hackerrank/env” instead of “set in docker-compose”. |
Your packaging script gets one new option, --hackerrank.
scripts/package_candidate.sh --hackerrankIt writes dist/policy-service-hackerrank.zip. Without the option the script still builds your Docker bundle as before.
tests/, seed/, docs/ for candidates, requirements.txt, hackerrank.yml, hackerrank/, and hackerrank/Makefile placed as Makefile.docker-compose.yml, Dockerfile, scripts/, docs/HACKERRANK_SETUP.md, docs/INTERVIEWER_README.md, seed/credentials.json, seed/tokens.json, .claude/, dist/, caches and logs.#!/usr/bin/env bash
# Interviewer only: build the candidate bundle (what you upload to HackerRank) into dist/.
# Leaves out interviewer-only docs and scripts.
# scripts/package_candidate.sh Docker bundle: dist/policy-service-candidate.zip
# scripts/package_candidate.sh --hackerrank HackerRank bundle: dist/policy-service-hackerrank.zip
set -euo pipefail
cd "$(dirname "$0")/.."
MODE=docker
[ "${1:-}" = "--hackerrank" ] && MODE=hackerrank
OUT=dist/policy-service
rm -rf dist && mkdir -p "$OUT"
rsync -a \
--exclude '.git' --exclude '.claude' --exclude 'dist' --exclude '__pycache__' --exclude '*.pyc' \
--exclude '.pytest_cache' \
--exclude 'docs/INTERVIEWER_README.md' --exclude 'docs/HACKERRANK_SETUP.md' \
--exclude '/=' --exclude '/exporting' \
--exclude 'scripts' --exclude 'seed/credentials.json' --exclude 'seed/tokens.json' \
--exclude 'tests/hidden' --exclude 'reference-solution' \
--exclude '.venv' --exclude '.cache' --exclude '.run' --exclude 'logs' --exclude 'test-results' \
./ "$OUT/"
if [ "$MODE" = hackerrank ]; then
# HackerRank cannot run Docker: ship the native setup and its Makefile instead of the compose files
rm -f "$OUT/docker-compose.yml" "$OUT/Dockerfile"
cp hackerrank/Makefile "$OUT/Makefile"
else
rm -rf "$OUT/hackerrank" "$OUT/hackerrank.yml"
fi
# sanity checks: nothing interviewer-only leaked (e.g. grading tests copied back in after an interview)
LEAKS="INTERVIEWER\|reference-solution\|tests/hidden\|test_repro\|planted\|gives away\|give away"
if grep -rIl "$LEAKS" "$OUT" >/dev/null 2>&1; then
echo "WARNING: interviewer-only references found in the bundle:"
grep -rIn "$LEAKS" "$OUT"
fi
if [ "$MODE" = hackerrank ]; then
# HackerRank expects the project files at the root of the zip
(cd "$OUT" && zip -qr ../policy-service-hackerrank.zip .)
echo "built dist/policy-service-hackerrank.zip"
else
(cd dist && zip -qr policy-service-candidate.zip policy-service)
echo "built dist/policy-service-candidate.zip"
fiThe question editor has three steps on the left. The zip goes in step 2.
dist/policy-service-hackerrank.zip. The file list should then show hackerrank/, hackerrank.yml and Makefile, and no Docker files.hackerrank.yml and shows Install bash hackerrank/setup.sh, Run make up, Test make test.bash hackerrank/score.sh and the output file test-results/junit.xml. Click Validate. HackerRank runs the scoring command, which takes a few minutes.hackerrank folder and hackerrank.yml, and no Docker files. The cloud icon above the file list is Import Project.hackerrank.yml. Validate is at the bottom right.To update an existing question later, open it with Edit, go to step 2A and upload the new zip the same way. A new upload replaces all project files.
Add the question to a test, click Try Test, and wait for setup to finish.
make restart and 12 passed. The admin page with the demo rules is in the preview pane on the right.Run these in the IDE terminal:
grep -n 'bash "$0"' hackerrank/services.sh # 2 lines
make status # everything up
make restart && make test # 12 passedmake restart stops and starts all five services without an error.make test shows 12 passed.make status shows what is up.kafka-python 2.0.2 does not import on newer Python and does not support Kafka 4.~/.local/share/policy-engine). make reset wipes it and starts fresh.make up with your own Makefile and docker-compose.yml is unchanged.