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

# DrawSplat installation without Docker: 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 Node.js, MariaDB/MySQL, Caddy, 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 → Node/database/Caddy → 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; Node/npm, database, and Caddy 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. Use the official OS-specific Node.js downloads (https://nodejs.org/en/download), MariaDB installation guidance (https://mariadb.com/docs/server/mariadb-quickstart-guides/installing-mariadb-server-guide) or MySQL installation guidance (https://dev.mysql.com/doc/refman/8.4/en/installing.html), and Caddy instructions (https://caddyserver.com/docs/install). This skill uses native host processes; do not run Docker or the Docker launchers. 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 the native software for this OS.** Use the package guide's supported Node.js/npm, MariaDB (default) or MySQL, and Caddy versions; current guidance calls for Node 22 or newer, MariaDB 11.8 or MySQL 8.4, and Caddy 2. Use official OS/architecture-specific packages and explain each role. Check existing versions, running services and occupied ports first. Keep existing installations intact; do not replace the laptop's working database, stop unrelated services, or reset root credentials. The user handles OS privilege prompts. Verify `node --version`, `npm --version`, `caddy version`, and an actual database connection. Configure the database packet limit as instructed (currently at least 32 MB), explaining that larger whiteboards need it. No PHP, Docker, or Python launcher is needed for this district native path.
3. **Provision a dedicated database.** With authorized database-administrator access, create a new empty UTF-8 (`utf8mb4`) database and a dedicated database-specific application user. Follow the guide's migration and record-access grants; never connect the application as root. Resolve an existing database/name conflict without deleting anything. Explain TCP host/user matching (the guide uses `127.0.0.1`, port 3306), and verify access as the application user, not only as root. Let the user choose and privately store the unique database password. Run credential-containing SQL privately and exclude it from logs, screenshots, and recording. Do not substitute example passwords as working defaults.
4. **Save the native plan.** Open root `start-here.html`, choose **Without Docker**, choose the same database engine provisioned above, leave all components checked unless the user selects otherwise, and keep the domain blank for localhost. Save the installation plan inside the inner `drawsplat/` application folder; verify it exists there. This is separate from creating the database. Use a fresh directory for native setup; selecting this path does not migrate a Docker installation.
5. **Launch native services with one command.** After OS software and database provisioning, run `bash start-native.sh` (Linux/macOS) or `start-native.bat` (Windows) from the inner `drawsplat/` folder. Explain its three chapters: install API dependencies, prepare/validate configuration, and start Node API plus Caddy in one foreground session. Keep that terminal open; Ctrl+C stops both processes. Use the printed setup address/key privately. Its readiness message proves service response, not completed setup. If ports are occupied, inspect the owner and use the documented port options; do not kill unrelated services. For OS-managed services, use the separate runner/gateway commands from the package guide instead of starting a duplicate combined launcher.
6. **Complete the local web installer.** Open `/setup` at the printed gateway address and enter the setup key privately. Explain and enter the provisioned database host, port, name, dedicated username and private password. Test the connection. For a remote database follow verified TLS instructions; keep this demonstration local unless instructed otherwise. Show where initial district-administrator credentials are generated and let the user keep or replace them according to the installer requirements; there is no universal password. Finish setup, privately save login details, verify the native API restarts automatically, and verify first-time setup closes. Preserve `selfhost/district/native-private/settings.json` and `config.json` with administrator-only permissions (NTFS on Windows); the latter includes database credentials and the password pepper. Generated gateway files live in `native-web/`; do not serve private files through another web server.
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. **Native restart, rerun, and backups.** Explain that closing the initial API/Caddy terminals stops those processes; the database is a separate OS service. Record the combined launcher command and folder, or the separate commands if OS-managed services were configured. Stop only this installation's processes gracefully, restart, and verify the saved board, login and classroom persist. Rerun native preparation with the same plan and preserve private configuration; do not repeat first-time setup, change engines, or recreate the database. If unattended startup is requested, use the package's OS-specific systemd, Windows service/startup-task, or macOS launchd guidance with correct paths, account permissions and restart behavior; test it rather than claiming terminals automatically become services. Keep public HTTPS/DNS changes out of the localhost tutorial unless explicitly requested.

    For backup, use the guide's native `mariadb-dump`/`mysqldump` procedure with password prompting, an OS-appropriate private `--result-file` path, and the supplied transaction/no-lock/no-tablespaces options. Copy the matching private configuration securely; explain why the password pepper must accompany account data. Docker backup scripts do not back up this native installation. Verify the backup files exist and record their locations without revealing contents. Test restore only into an isolated disposable database/installation with the matching configuration; never import over the demonstration database. If no restore is performed, mark recovery untested. Seek explicit authorization before any destructive reset, database drop, or replacement of private configuration.


## 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.