User Testing Guide

On this page

What Is This Guide?

CRAIG is an open-source child welfare information system. This guide walks you through running a complete copy of CRAIG on your own computer so you can explore it, test workflows, and provide feedback — no programming knowledge required.

CRAIG runs locally using Docker (software that creates isolated environments on your computer, similar to running a program inside a sealed container that does not affect anything else on your machine). All data stays on your computer. The test data loaded into CRAIG is entirely fictional — no real families or children.

Time estimate: 20-30 minutes for first-time setup (including downloads). After the first time, starting CRAIG takes about 1-2 minutes.

What You Will Need

  • A Windows, macOS, or Linux computer

  • At least 16 GB of total RAM (CRAIG needs 8 GB allocated to Docker, and your computer needs memory for everything else)

  • About 10 GB of free disk space (for Docker and CRAIG)

  • An internet connection (to download Docker and CRAIG — after setup, CRAIG runs offline)

  • Administrator access on the computer (to install Docker)

If your agency laptop restricts software installation, you may need to ask your IT department to install Docker Desktop for you. Show them this guide — the only software to install is Docker Desktop.

Step 1: Install Docker

You need two things installed: Docker and the xtask task runner.

For developers (Rust toolchain installed): cargo xtask works automatically — skip the xtask download.

For non-developers (no Rust): Install Rust (follow default prompts), then cargo xtask will work. Pre-built xtask binaries will be available in future releases.

Find the section below for your operating system to install Docker.

Windows

Install Docker Desktop

  1. Go to https://www.docker.com/products/docker-desktop/ and click Download for Windows.

  2. Run the downloaded installer. Accept the default settings. When asked about "WSL 2" versus "Hyper-V," choose WSL 2 (recommended).

  3. When installation finishes, restart your computer.

  4. After restarting, Docker Desktop starts automatically. You may see a brief "Docker Desktop is starting" window — wait for it to finish. A small whale icon will appear in your system tray (bottom-right corner of the taskbar, near the clock).

If you see a message about "WSL 2 installation is incomplete," follow the link Docker provides to install the WSL 2 update, then restart Docker Desktop.

Allocate Memory

  1. Right-click the Docker whale icon in the system tray and select Settings (or open Docker Desktop from the Start menu).

  2. In the left sidebar, click Resources.

  3. Find the Memory slider. Drag it to at least 8.00 GB. If your computer has 16 GB, 8 GB is the right setting.

  4. Click Apply & restart at the bottom.

On Windows with WSL 2, Docker Desktop may say "Resource allocation is managed by WSL." In that case, Docker shares memory with WSL automatically. If CRAIG has trouble starting later, see the Troubleshooting section for how to set a memory limit manually.

Verify Installation

  1. Press the Windows key, type PowerShell, and click Windows PowerShell.

  2. Type the following command and press Enter:

    docker --version

  3. You should see something like Docker version 28.x.x, build …​. If you see an error, Docker is not installed correctly — try restarting your computer and reopening Docker Desktop.

macOS

Install Docker Desktop

  1. Go to https://www.docker.com/products/docker-desktop/ and click Download for Mac.

  2. Choose the correct version for your Mac:

    • Apple Silicon (M1, M2, M3, M4 — most Macs from 2021 onward)

    • Intel (older Macs)

      Not sure which you have? Click the Apple menu ({apple}) > About This Mac and check whether it says "Apple M…​" or "Intel."

  3. Open the downloaded .dmg file and drag Docker to your Applications folder.

  4. Open Docker from Applications. The first time, macOS may ask for your password — enter it to grant permissions.

  5. A whale icon appears in the menu bar (top of the screen). Wait for it to stop animating — this means Docker is ready.

Allocate Memory

  1. Click the Docker whale icon in the menu bar and select Settings (or Preferences on older versions).

  2. Click Resources in the left sidebar.

  3. Set Memory to at least 8.00 GB.

  4. Click Apply & restart.

Verify Installation

  1. Press Cmd+Space, type Terminal, and press Enter.

  2. Type the following command and press Enter:

    docker --version

  3. You should see something like Docker version 28.x.x, build …​.

Linux (Ubuntu / Debian)

Install Docker Engine

  1. Open a terminal (usually Ctrl+Alt+T or find "Terminal" in your applications menu). A terminal (also called a command prompt) is a text-based window where you type commands.

  2. Run these commands one at a time. You will be asked for your password:

    sudo apt-get update
sudo apt-get install -y docker.io docker-compose-v2
sudo usermod -aG docker $USER

You must log out and log back in (or restart your computer) after the last command. If you skip this step, Docker commands will fail with a "permission denied" error.

Verify Installation

After logging back in, open a terminal and run:

docker --version
docker compose version

Both commands should show version information. If docker gives a permission error, you did not log out and back in after the previous step.

On Linux, Docker uses your computer’s available memory automatically. No memory allocation step is needed — just make sure your computer has at least 8 GB of RAM total.

Step 2: Get the CRAIG Source Code

You need a copy of the CRAIG source code on your computer. Choose one of the two options below.

Option A: Download as a ZIP File (Easier)

  1. Go to https://gitlab.com/gadhs/application/ccwis/craig

  2. Near the top-right of the page, click the download icon (a downward arrow), then click Download source code and choose zip.

  3. Open the downloaded ZIP file and extract (unzip) it to a folder you can find easily:

    • Windows: C:\Users\YourName\craig

    • macOS / Linux: ~/craig (your home folder)

Option B: Clone with Git

If you have Git installed (your IT department may have set it up), open a terminal and run:

git clone https://gitlab.com/gadhs/application/ccwis/craig.git

Open a Terminal in the CRAIG Folder

You need a terminal window (also called a command prompt) pointed at the CRAIG folder.

Windows:

  1. Open File Explorer and navigate to the craig folder.

  2. Click the address bar at the top (where the folder path is shown), type powershell, and press Enter. This opens PowerShell already pointed at the CRAIG folder.

macOS / Linux:

Open Terminal and type:

cd ~/craig

Replace ~/craig with the actual path if you put it somewhere else.

Verify you are in the right place:

ls Cargo.toml

You should see the file listed. If you get an error, you are in the wrong folder — double-check the path.

Step 3: Start CRAIG

From the terminal in the CRAIG folder, run:

cargo xtask dev start
This command works on all platforms (Windows, macOS, Linux). If you downloaded the pre-built xtask binary, run ./xtask dev start instead.

What to Expect During Startup

The startup process takes several steps:

  1. Building — Docker downloads and builds the software components. The first time, this downloads about 2-3 GB and takes 5-10 minutes depending on your internet speed. You will see a lot of text scrolling by — this is normal.

  2. Starting infrastructure — The database, message system, login server, and file storage start up.

  3. Starting CRAIG services — The CRAIG modules (rules, cases, placement, exchange, financial, reporting, security, public intake, composition) and the web interface start up and connect to the infrastructure.

  4. Initializing storage — File storage is configured (happens automatically).

  5. Health checks — Each service reports "healthy" as it becomes ready.

  6. Loading test data — Fictional families, cases, referrals, placements, and financial records are loaded.

When everything is ready, you will see:

==> Waiting for services to become healthy...
    craig-rules          healthy
    craig-cases          healthy
    craig-placement      healthy
    craig-exchange       healthy
    craig-financial      healthy
    craig-reporting      healthy
    craig-security       healthy
    craig-intake         healthy
    craig-composition    healthy
    craig-web            healthy
==> Verifying seed data...
    Seed completed successfully.

  Service                  URL
  ─────────────────────────────────────────
  craig-web                 http://localhost:39363
  keycloak                  http://localhost:43319
  postgres                  localhost:43333
  rabbitmq                  http://localhost:43187

==> CRAIG devstack is ready.

CRAIG picks random free network ports each time it starts (so it never conflicts with other software on your computer). The port numbers you see will be different from the example above. Write down or copy the craig-web address — that is the address you will open in your browser in Step 4. If you lose it, run cargo xtask dev status and read the first number in craig-web’s PORT(S) column, or look in the .ports.env file in the CRAIG folder.

The first startup takes 5-10 minutes because Docker must download base images and build the software. After the first time, startup takes 1-2 minutes because everything is cached.

If startup seems stuck or takes more than 15 minutes, see the Troubleshooting section below.

Step 4: Log In

  1. Open your web browser (Chrome, Firefox, or Edge all work).

  2. Go to the craig-web address printed at the end of startup (for example http://localhost:39363 — your port number will be different, because CRAIG picks a random free port each time it starts).

  3. You will see the CRAIG landing page with the title "CRAIG — Child Rights Advocacy & Information Governance" and a blue Sign In button.

  4. Click Sign In. You will be redirected to a login form.

  5. Enter one of the usernames and passwords from the table below.

  6. Click Sign In on the login form.

  7. You will be redirected to the CRAIG dashboard.

Test User Accounts

CRAIG comes with seven test users, each with different roles and access levels. Try logging in as each one to see how the system looks from different perspectives.

Username Password Role What You Can Access

admin

password

Administrator

Everything — all modules, including Rules and Security. Use this account to explore the full system.

jane.doe

password

Caseworker + Supervisor

Dashboard, Intake, Cases, Placement, Exchange, and Financial. This is the closest to a typical supervisor’s view.

bob.smith

password

Caseworker + Eligibility Worker

Dashboard, Intake, Cases, Placement, and Financial. This is the closest to a caseworker handling IV-E eligibility determinations.

carol.reader

password

Read-only

Read-only views where a module grants the readonly role access. This is the auditor/reviewer perspective — nothing can be created or changed.

dana.county

password

Supervisor + County Director

Everything a supervisor sees, plus county-level approval authority in the subsidy review workflow.

rita.regional

password

Supervisor + Regional Director

Everything a supervisor sees, plus regional-level approval authority in the subsidy review workflow.

sam.state

password

Administrator + State Office

Everything an administrator sees, plus state-office (highest) approval authority in the subsidy review workflow.

To switch users, click Logout in the top-right corner of the screen, then log back in with a different username.

Step 5: Explore CRAIG

After logging in, you start on the Dashboard. The navigation bar across the top of the screen shows the modules available to your role. Here is what each module contains.

Dashboard

Summary tiles relevant to your role. Caseworkers see their caseload and overdue tasks. Administrators see system-wide statistics.

Intake

Click Intake to see the referral worklist — incoming reports of child abuse or neglect. Click any referral to view its details, including the investigation and safety assessment. Try creating a new referral using the New Referral button.

Cases

Click Cases to see a list of open child welfare cases. Click into a case to see its full record: case plans, contacts, court orders, household members, tasks, and placement history. Try creating a new case using the New Case button.

Placement

Click Placement to see placement matching, the list of foster homes, and current placements. Explore a foster home record to see training history, household members, and licensing details. The placement matching screen shows how children are matched to available homes based on needs and availability.

Financial

Visible to: eligibility worker, supervisor, and administrator accounts.

Click Financial to see payments, rate tables, and claiming records. Explore a payment to see its details, adjustments, and Title IV-E eligibility status.

Exchange

Visible to: supervisor and administrator accounts.

Click Exchange to see data exchange partners, agreements, ICPC (Interstate Compact on the Placement of Children) requests, and data transactions. This module handles interstate placements and data sharing with external partners.

Rules

Visible to: administrator account only.

Click Rules to see the policy rule sets loaded into the system. These are the configurable business rules that drive safety assessments, eligibility determinations, and intake screening decisions.

Security

Visible to: administrator account only.

Click Security to see the audit log, security reviews, NIST controls, and archive records. The audit log captures all significant events across the system.

Stopping CRAIG

When you are done testing, stop CRAIG to free up your computer’s resources.

cargo xtask dev stop

This stops everything but keeps your data. The next time you start CRAIG, it will resume where you left off with the same test data.

Starting with Fresh Data

If you want to wipe all data and start with a clean set of test data:

cargo xtask dev restart

This removes everything, rebuilds, and reloads the test data from scratch. It takes a few minutes, similar to the first startup.

Checking Status

To see whether CRAIG is running and which services are healthy:

cargo xtask dev status

You will see a table showing each service’s state and health:

CRAIG Devstack Status
=====================

Infrastructure:
  SERVICE              STATE      HEALTH     PORT(S) host:container     UPTIME
  -------              -----      ------     ----------------------     ------
  postgres             running    healthy    43333:5432                 5 minutes
  postgres-test        running    healthy    41341:5432                 5 minutes
  rabbitmq             running    healthy    45293:5672, 43187:15672    5 minutes
  keycloak             running    healthy    43319:8080                 5 minutes
  garage               running    healthy    46361:3900, 37415:3903     5 minutes

Services:
  SERVICE              STATE      HEALTH     PORT(S) host:container     UPTIME
  -------              -----      ------     ----------------------     ------
  craig-rules          running    healthy    33107:8001                 4 minutes
  craig-cases          running    healthy    39421:8002                 4 minutes
  craig-placement      running    healthy    33585:8003                 4 minutes
  craig-exchange       running    healthy    34005:8004                 4 minutes
  craig-financial      running    healthy    36143:8005                 4 minutes
  craig-reporting      running    healthy    46463:8006                 4 minutes
  craig-security       running    healthy    43145:8007                 4 minutes
  craig-intake         running    healthy    32965:8008                 4 minutes
  craig-composition    running    healthy    35313:8009                 4 minutes
  craig-web            running    healthy    39363:8080                 4 minutes
  mock-server          running    healthy    33097:9090                 4 minutes

Each PORT(S) entry reads host:container — the number on the left is the randomly assigned port on your computer (this is the one you can open in a browser or connect to); the number on the right is the fixed port inside Docker. The host-side numbers change every time CRAIG starts, so yours will differ from the example.

All services should show "running" and "healthy." If any service shows "unhealthy" or is missing, try stopping and starting CRAIG again.

Troubleshooting

"Docker is not running" or "Cannot connect to Docker daemon"

Docker Desktop must be running before you can start CRAIG.

  • Windows: Look for the whale icon in the system tray (bottom-right, near the clock). If you do not see it, open Docker Desktop from the Start menu.

  • macOS: Look for the whale icon in the menu bar (top of the screen). If you do not see it, open Docker from Applications.

  • Linux: Run sudo systemctl start docker to start the Docker service.

Startup Takes More Than 15 Minutes

The most common cause is not enough memory allocated to Docker.

  • Windows / macOS: Open Docker Desktop > Settings > Resources and set Memory to at least 8 GB. Click "Apply & restart."

  • Windows with WSL 2: If Docker says "Resource allocation is managed by WSL," create a file called .wslconfig in your user folder (C:\Users\YourName\.wslconfig) with these contents:

    [wsl2]
memory=8GB

    Then close Docker Desktop and reopen it.

  • Linux: Make sure your computer has at least 8 GB of RAM. Run free -h to check.

"Port Is Already in Use" Error

CRAIG picks random free network ports each time it starts, so this error is rare and usually temporary (another program grabbed the same port in the split second between CRAIG choosing it and Docker using it). Simply run the start command again — CRAIG will pick a fresh set of ports. If it keeps happening, restart your computer and try again.

The Web Page Does Not Load

  1. Make sure CRAIG finished starting (you should see =⇒ CRAIG devstack is ready. in the terminal).

  2. Wait 30 seconds after startup and try again — the web interface may still be initializing.

  3. Make sure you are using the craig-web address from the end of the startup output — the port number changes every time CRAIG starts, so an address from a previous session will not work. Run cargo xtask dev status to see the current port (the first number in craig-web’s PORT(S) column).

  4. Make sure the address starts with http:// (not https — CRAIG’s test environment does not use HTTPS).

  5. Check the status of services using the status command (see Checking Status). All services should show "healthy."

The Login Page Appears but Signing In Fails

The login server may still be starting up. Wait 1-2 minutes and try again. Make sure you are using the exact username and password from the Test User Accounts table — usernames are case-sensitive.

Everything Was Working, but Now I Get Errors

  • Session expired: If CRAIG has been running for more than 30 minutes, your login session may have expired. Click Logout and log back in.

  • Data corruption: If the system behaves unexpectedly, start fresh by running the restart command (see Starting with Fresh Data).

For More Information

This guide covers everything you need to evaluate and test CRAIG. For more detailed information, see:

  • DevStack Guide — Full technical reference for the test environment, including all services, ports, configuration, and developer workflows.

  • Architecture — How CRAIG’s services are designed and how they communicate.

  • Why CRAIG? — The case for open-source child welfare systems.

  • CRAIG on GitLab — Source code, issue tracker, and project updates.

Edit this page · latest