---
name: drawsplat-local-install
description: Guide and document a fresh local installation of the complete DrawSplat and SplatWorks district suite, including Docker, MariaDB, administrator setup, rosters, and classroom verification, using available computer-agent tools or guided manual steps.
---

# DrawSplat local installation guide and recorder

Help the user install the complete district suite on their own computer, learn each step, and keep a reproducible installation record. This workflow begins at https://drawsplat.org/pages/download and ends with a verified local whiteboard, database-backed saving, classroom demonstration, and documented restart/backup procedures. It does not authorize public deployment or replacing existing installations. For Docker, a second extracted folder alone is not isolated: the default Compose project name shares services/volumes. Test a fresh revised installer on a disposable VM or separate host when an unfinished stack must remain intact.

## Start the session

Establish the operating system/version, architecture, available administrator access, and whether Docker or a previous DrawSplat installation already exists. Ask whether “record” means a written guide with screenshots, a screen recording, or both. Default to a written log with non-sensitive screenshots until the user chooses video. Do not install anything merely because this skill was attached; begin when the user asks to perform the installation.

Inspect available capabilities. A Chrome/browser extension may control websites but lack access to downloaded files, desktop installers, terminals, and screen recording. State that boundary and guide the user through those steps. Use native or terminal tools only when available and authorized. Never claim a click, installation, command, recording, or successful test that was not observed. Do not depend on a particular extension name, tool API, or skill-import feature. If skill importing is unavailable, treat this file as attached/pasted task instructions.

Group terminal work into coherent chapters with a single checkpoint after each chapter; do not split every readiness command into a separate “done” exchange. State desktop/privilege limitations before beginning and provide one consolidated command block per OS chapter.

Offer a short sequence: download → Docker → Quick Start → database/admin → classrooms → verification → backup/restart. In guided mode explain one manageable step, wait for the user's result, and continue. In agent mode perform authorized actions, narrate milestones, and pause where the user must handle an OS privilege prompt, reboot, login, or secret entry. Existing authorization persists; do not repeatedly request routine confirmation.

## Explain the installation for the viewer

Treat this as a narrated tutorial for a district administrator encountering the tools for the first time. Before each action explain **what we are doing**, **why it is needed**, **where to click or run the command**, and **what success will look like**. Afterward describe the visible result and the next step. Define unfamiliar terms as they first appear; avoid silently issuing a stream of commands.

Explain that the whiteboard and SplatWorks are browser applications, the API handles accounts and classroom saving, the database stores records, and the gateway serves the site and routes requests to the API. Explain that `localhost` refers to this computer, ports distinguish services, a terminal runs commands, and its current folder affects relative paths. Distinguish opening the extracted Quick Start HTML from opening the running local website. Explain the separate database and district-administrator credentials before showing those forms.

Describe each command in plain language before running it. Show commands appropriate for the user's OS, identify the required working directory, and tell the viewer when to keep a terminal open. For downloads, name the exact package and explain why the district suite is required. For the checksum, explain that matching hashes confirm the downloaded archive matches the published file. For component choices, explain what unchecking an app changes. For recording, introduce each chapter, capture a non-sensitive result, and summarize the verified checkpoint. Add these explanations to the written installation record, not just the spoken narration.

For Docker, explain containers as managed services, Compose as the tool that starts the cooperating services, and volumes as persistent storage that survives container restarts. For native setup, explain that Node runs the API, MariaDB/MySQL runs as a separate database service, and Caddy serves the website; these must be installed and started separately. Do not imply a browser extension can control an OS installer merely because it can fill web forms.

## Recording and session continuity

Start `drawsplat-installation-record.md` outside the application webroot, or maintain the record in the conversation if file writing is unavailable. Record:

- Date/time and timezone; OS/architecture; browser; Docker/Compose versions.
- Download page, exact package URL/version, checksum source/result, extraction path, and local origin.
- Selected hosting path, database engine, component choices, and completed checkpoints.
- Each action/command, observed result, time, and a redacted screenshot reference where useful.
- Errors, exact non-secret error text, attempted fixes, and the confirmed resolution.
- Credential storage location without credential contents; backup location; restart instructions; remaining work.

Use checkpoint states **not started**, **in progress**, **verified**, **blocked**, and **skipped by user**. An action without observed evidence is not verified. At interruption, save the last verified checkpoint, current screen, and next action; resume by inspecting state instead of repeating installation blindly.

If video is requested, first record a short non-sensitive test: verify start, pause, resume, stop, saved location, and playback. If these cannot be confirmed, mark video unverified and ask whether to continue with a written tutorial. Then use an available recorder or guide the user to their OS recorder. Confirm that recording actually started and where it will be saved. Capture only the relevant app/window where supported. Pause recording and avoid screenshots while setup keys, generated passwords, database credentials, OAuth tokens, or personal accounts are visible. Resume after secret screens close. Do not place secrets in the transcript, clipboard log, exported guide, or video. If continuous recording cannot be paused/redacted, defer capture of those steps and describe them afterward. Report written logs, screenshots, and video separately; never label screenshots as a video recording.

## Use the current installation instructions

Start at the authoritative, searchable SplatWorks Wiki (https://drawsplat.org/wiki/), then read the current download page and https://drawsplat.org/docs/district-selfhost.html. After extraction, use the included `start-here.html` and guide for that package version as the command reference. Follow official Docker OS instructions at https://docs.docker.com/get-started/get-docker/ and its linked Windows/macOS/Linux installation pages. Do not freeze release numbers, package sizes, app counts, runtime requirements, or installer commands into the session.

1. **Download the district suite.** Select **Download complete DrawSplat + SplatWorks district suite**, in the district MariaDB/MySQL section. Do not substitute the browser-only complete whiteboard ZIP, a SplatWorks-only ZIP, or a source archive merely because its label says “complete.” Record the exact selected release. Download its matching SHA-256 file, verify the archive with the OS-appropriate command in the guide, and stop on mismatch. Extract the entire ZIP into a new folder; do not overwrite another installation. Expected district layout: root `start-here.html` beside the `drawsplat/` payload folder. If these or the district launchers are absent, inspect the package and resolve the mismatch before proceeding.
2. **Install Docker for this OS.** Windows: official supported Desktop/WSL path and Linux containers; handle virtualization/WSL/restart requirements as shown by the installer. macOS: select the correct Apple silicon/Intel installer. Linux: use the distribution's official Docker Engine repository and the `docker compose` plugin instructions. Inspect existing installations before changing packages; do not uninstall unrelated container software or alter system security to bypass a failure. The user handles privilege prompts and license decisions. Keep localhost as the destination; no public firewall or router changes.
On Debian 12/13, prefer the package’s staged `scripts/install-docker-debian.sh` helper when present; explain its inspect/install/verify chapters and use authorized sudo locally. It does not remove conflicting software or reset existing Docker.
3. **Verify Docker readiness.** Confirm `docker version`, `docker compose version`, `docker compose up --help` support for `--wait` and `--wait-timeout`, a running Linux-container daemon (`docker info`), and `docker run --rm hello-world`. Record the observed versions/results. If a privilege/reboot/logout step is needed, explain it and wait. Never make the Docker socket world-writable. The Docker path supplies Node and the database: no host PHP, Node, Python, or separate MariaDB installation is required for this path.
4. **Plan the installation.** Open root `start-here.html`. Select **Docker (preferred)** at the outset; leave all component checkboxes selected unless the user chooses otherwise. Choose bundled **MariaDB** unless MySQL is explicitly requested; keep the domain blank for localhost. Save the installation plan in the inner `drawsplat/` folder by the guide's folder-picker/download procedure, and confirm the file actually exists in the required location. A downloaded plan still sitting in Downloads is not an applied plan. For Docker, use the launcher’s `--plan` option with the full downloaded path, avoiding manual file moves; confirm its **Applied plan** summary matches the choices. Do not quietly fall back to native setup when Docker is blocked; explain the issue and obtain the user's path choice.
5. **Launch from the payload folder.** Open a terminal in `drawsplat/`, containing `start-district.sh` and `start-district.bat`. Use the matching launcher (`bash start-district.sh` on Linux/macOS; `start-district.bat` on Windows) and current guide options. Verify completion/container health rather than assuming success when a browser opens. Use the URL and setup key actually printed by this run; the usual local origin is `http://localhost:8080`. Store the key privately, never in the installation log.
6. **Finish web setup.** Open the launcher's local `/setup` URL. The administrator enters the setup key privately. Keep **Bundled database** selected; the server ignores browser credential overrides in this mode. Database fields should be hidden and disabled. Test the connection. If the package instead shows the older blank-fields form, identify the older version and use an updated district package before continuing; preserve existing data. The generated and completed passwords should be masked by default. Show the administrator where the generated initial email/password are presented and let them keep or replace them according to the installer requirements. There is no universal default password. Keep database credentials, the district administrator account, teacher/student accounts, and any legacy Teacher Admin unlock password distinct. Complete setup, privately save the login details, and verify the API restarts and first-time setup closes.
7. **District administration and classrooms.** Open the local `/admin/district-roster.html`; sign in with the district administrator account just created. For a first demonstration use synthetic teachers/students and the bundled sample roster schema; review the CSV preview before importing. Verify the classroom, teacher assignment, and enrollments. Do not use real student data for a tutorial recording. Do not assume CSV-created Google accounts have usable password logins.
8. **School Google login when requested.** Follow the guide's OAuth Web Client steps: exact authorized JavaScript origin, client ID, permitted email domains, then matching teacher/student roster emails. The user signs into Google and enters credentials privately. No Google client secret is required for this browser ID-token flow. Do not create cloud projects, change district Google settings, or send invitations without task authorization. If access is unavailable, mark Google-dependent tests pending; an admin login or mocked sign-in does not prove teacher/student Google access works. Never promise arbitrary synthetic emails can sign in with Google.
9. **Verify the complete suite.** Open the local whiteboard; confirm a fresh board is blank, drawing works, and a local editable-file save/reopen works. Confirm district online Save/Open with an authenticated account. Use teacher/student accounts in separate browser profiles or sessions when available; verify assigned classroom visibility, sharing a board as an assignment, student turn-in, and teacher review. Teachers use their own school login, not a shared district administrator password. If a prerequisite is missing, record that test as pending. Open each selected component from the local suite launcher and record whether it loads; do not imply every app's separate connected service is configured simply because the page opens. Verify SplatWorks core local editing and one representative save/export without claiming its storage is MariaDB-backed unless actually demonstrated.
10. **Restart, rerun, and backup.** Use the package's Docker backup/restore instructions; save backups outside the public app folder. Verify that a backup file is created. Test restore only in a separate disposable installation/database, or clearly label restore as untested. Restart the local stack and confirm the admin login, saved board, and classroom survive. Rerun the launcher from the same installation folder and verify preservation; do not reinitialize `/setup`, switch database engines over existing volumes, run `down -v`, delete volumes, or replace private configuration to “start fresh.” Explain and seek explicit authorization before any destructive reset. Document the current package's stop/start and backup commands with the correct working folder.

## Failure handling and completion

On an error, inspect the visible message and relevant redacted service logs before changing settings. Try a targeted fix and recheck the same checkpoint. After two failed attempts with the same unresolved cause, explain the blocker and request the specific missing access/information instead of looping or resetting data. Do not expose API/database ports to the network to fix localhost connectivity.

Finish with the local URLs, package/version, verified checkpoint list, pending prerequisites, credential/backup storage locations, restart procedure, and links to the saved recording artifacts. Separate a verified local demonstration from district production readiness: a local install does not validate classroom load, public HTTPS, retention policies, or disaster recovery. Only report tests actually performed. Do not publish a user's local recording or installation log without their instruction.