OCS-in-a-Kit · v0.2.0 · updated Nov 20, 2026

The Open Coding Society platform with the school taken out, packaged so any school or organization can run its own copy with one command.

3kits: Vanilla, Education, Business
16features, switched on or off by an Admin
4repositories: website, Flask, Spring, installer
1command to install everything

To install it, see Install OCS-in-a-Kit.

What OCS-in-a-Kit is

Open Coding Society runs a live website and two backend servers for its own school. That code holds school data, student information and API keys, so another school can't safely copy it.

OCS-in-a-Kit is a cleaned copy of the same platform. The school-specific parts are taken out, the features are grouped into kits, and an installer sets the whole thing up on a new school's own server.

Website

Jekyll site on GitHub Pages: lessons, guides, profile, admin dashboard. Repo: OCS-Kit-Pages.

Flask backend

Python API: logins, sections, AI chat proxy, code runner, social. Repo: OCS-Kit-Flask.

Spring backend

Java API: people, groups, assignments, calendar, hall pass. Repo: OCS-Kit-Spring.

Installer

One command asks a few questions, writes the settings and starts everything. Repo: OCS-Kit-Vanilla.

How to explain it
  • It's our platform with the school taken out, so any school can run its own copy.
  • There are four parts: the website, two backends, and an installer that ties them together.
  • A school runs one command and answers a few questions. It never has to read our code.

Three kits, one codebase

A kit is a preset: which features start switched on, and what the three roles are called. Every kit is built from the same code, so a fix made once reaches all three.

The choice is not final. An Admin can switch to another kit, or turn single features on and off, from the admin dashboard at any time. Accounts and data are kept; a feature that is turned off is hidden, not deleted.

KitVanilla

A simple site you can hand to a student.

AdminEditorUser
1 of 16 features on at the start
KitEducation

A computer science classroom.

AdminTeacherStudent
12 of 16 features on at the start
KitBusiness

An organization serving its own users.

AdminManagerMember
6 of 16 features on at the start
FeatureVanillaEducationBusiness
Core platformcore●●●
Lessonseducation·●·
Code runnersgeneral·●·
Assignments and gradingeducation·●·
Game enginegeneral·●·
AI chatbotgeneral·●●
AI gradingeducation·●·
Socialgeneral·●●
Calendargeneral·●●
Analyticsgeneral·●●
Hall passeducation·●·
Finance simulationgeneral···
Resume buildergeneral·●●
Kasm virtual desktopsgeneral···
Face recognitiongeneral···
Teaching examplesgeneral···

● on when the kit starts. Every other feature is an add-on an Admin can turn on later.

How to explain it
  • A kit is just a starting list of features plus role names: Teacher and Student, Manager and Member, or Editor and User.
  • All three kits are the same code. That's why we only fix things once.
  • Admins aren't locked in. They can change kits or features later without reinstalling.

A running kit

The website is only static files, served free by GitHub Pages. When someone signs in or opens anything with data, the page's JavaScript calls the backends.

The backends run in Docker on a server the school controls. nginx sits in front and handles HTTPS. Student code never runs inside a backend: it is sent to separate runner containers that have no internet access and strict memory and CPU limits.

Browser admin · staff · member loads pages Website GitHub Pages, static Docker Hub wolfjack20/ocs-in-kit compose pull YOUR SERVER · DOCKER COMPOSE HTTPS nginx TLS, one subdomain per backend ports bound to 127.0.0.1 only flask :8587 SQLite in data/flask socket :8500 spring :8585 · ws :8589 data in data/spring INTERNAL NET · NO INTERNET run code run code flask_runner Python, JavaScript · 512 MB spring_runner Java · 768 MB install.sh wrote flask.env, spring.env and the nginx configs
Keep the website and both backends on subdomains of one domain, or browsers block the login cookie.
How to explain it
  • Pages are static and free to host; the data lives on the school's own server.
  • nginx is the front door. The backends are never exposed directly.
  • Student code runs in a sealed box with no internet, so a bad program can't hurt the server.

Turning a feature on or off

Every feature is listed once, in kits/catalog.json. Each backend works out which features are on: it starts from the kit, then applies any switches an Admin flipped in the dashboard.

When a feature is off, its backend routes answer 404 and the website hides its links. Hiding links is for convenience. The real protection is the backend refusing the request.

kits/catalog.json 16 features 3 presets, role names preset Server .env KIT=education FEATURES=+finance-sim Kit picked by Admin stored in backend DB .env ignored while set otherwise if set Admin overrides per feature, on or off no restart needed Effective features one set per backend off feature: routes 404 GET /api/kit Website asks both backends on only if both say on Site build _config.yml kit: used before any answer
Only the Admin role can change features, and the backends enforce it. If a backend stops answering, the website keeps its last answer, so a feature an Admin turned off stays off.

Four places to change features, from slowest to fastest:

Installer

Pick a kit and tick features while installing.

Backend .env

KIT=education, FEATURES=+finance-sim. Applies on restart.

Website _config.yml

kit: name: and features:. Applies on the next site build.

Admin dashboard

Admin → Manage features. Applies immediately, no restart.

How to explain it
  • One file lists every feature and which kit gets which.
  • The Admin dashboard is the normal way to change things, and it takes effect right away.
  • Turned-off features are blocked by the backend, not just hidden on the page.

Where the code comes from

New work is built in the live Open Coding Society repos. It moves into the kit through an import tool that copies one feature at a time and runs a scrub check on every file.

The scrub check blocks school names, keys and tokens, student data files and oversized files. If it finds anything, nothing is copied. What passes lands on a review branch, and a person merges it.

UPSTREAM IMPORT KIT REPOS WHAT THEY PRODUCE Open Coding Society live school repos pages flask spring school data, real keys reads OCS-Kit/sync scan import update scrub check run by hand today weekly job: not on yet opens PR OCS-Kit-Vanilla installer · catalog · sync OCS-Kit-Pages Jekyll website OCS-Kit-Flask Python API OCS-Kit-Spring Java API fork PR back CSA-Admin-OCS/* forks, origin for clones clone on push image image install.sh / install.bat asks questions, starts server GitHub Pages site static HTML and JS Docker Hub 0.3.0 wolfjack20/ocs-in-kit tags: flask- spring- socket- flask-runner- spring-runner-
Orange labels mark parts that are planned but not running yet.
How to explain it
  • We never copy upstream as a whole. Features come over one at a time.
  • Every file is scanned for school data and secrets before it can enter the kit.
  • The kit repos then produce three things: the installer, the website and the Docker images.

Keeping up with upstream pages

Main development happens in Open-Coding-Society/pages, and it moves fast. To keep the kit current without letting school data in, we run the same loop every week: scan, sort, bring things in one feature at a time, review, ship.

The scan and the tests are already written as GitHub workflows. They still need to be installed, so today they are run by hand.

~830

commits to upstream pages since the last scan

Oct 26

date of the last scan

Weekly

how often we plan to check from now on

Open-Coding-Society/ pages main development Weekly scan report posted to an issue workflow to install Triage update · import · skip bring in skip Branch + scrub update/<feature> import/<feature> exclude list stops showing in scans Pull request kit tests run a person reviews merge OCS-Kit-Pages site rebuilds fixes that belong upstream: report them there
The highlighted path is the one most items take. Flask and Spring follow the same loop with their own configs.
  1. Monday, automaticScanA workflow compares upstream with the kit and posts a report to one issue.
  2. Weekly, ~30 minTriageSort every item: update, import or skip.
  3. One feature per branchBring it inThe sync tool copies it, runs the scrub check and opens a pull request.
  4. Every pull requestReviewKit tests run; a person checks the pages in each kit.
  5. Merge, monthly tagShipMerging rebuilds the site. Once a month, tag a release and rebuild images.

The three triage buckets:

Update

Upstream changed a file in a feature the kit already has. update --feature lessons pulls just those changes.

Import

Upstream built something new worth having. import --feature game-engine --paths … brings it in with everything it depends on.

Skip

School-specific or personal pages. Add them to exclude in kit.sync.json so they stop showing up.

Keep kit-only changes in protected files like _config.yml and kits/**, so updates never overwrite them.
Report bugs that also exist upstream to the upstream team, so the next update brings the fix.
Never copy files from upstream by hand or cherry-pick commits. Both skip the scrub check.
Don't let it pile up. A skipped month is about a thousand commits to sort through.
Show the commands
python3 sync/ocs_kit_sync.py scan --kit ../OCS-Kit-Pages -o sync/reports/pages-scan-$(date +%F).md
python3 sync/ocs_kit_sync.py update --kit ../OCS-Kit-Pages --feature lessons --pr
python3 sync/ocs_kit_sync.py import --kit ../OCS-Kit-Pages --feature game-engine --paths _projects/games/voidstriker --pr

Run them from OCS-Kit-Vanilla. Add --dry-run to see the plan without writing anything. One-time setup: copy sync/workflows/upstream-scan.yml and kit-tests.yml into OCS-Kit-Pages/.github/workflows/ and set the repository variable OCS_KIT_REPO to Open-Coding-Society/OCS-Kit-Vanilla.

How to explain it
  • Upstream is where new features are built; the kit pulls from it every week.
  • Every change comes in on its own branch and goes through the scrub check and tests before anyone merges it.
  • Weekly matters: upstream gets about 30 commits a day, so small regular updates are much easier than a big catch-up.

Flask only or Flask + Spring

A teammate already solved part of packing out upstream. One spring setting in _config.yml decides whether the site uses Flask alone or Flask and Spring (pages #1844). Instead of checking if (springEnabled) all over the code, the site picks a class once: FlaskSession, or SpringSession, which extends it.

In his review, Mr. Mortensen called the switch the right way to manage shared code and the inheritance technique "far superior". He sees kits as a combination of three things, labelled A, B and C below. The kit will adopt this. Today the kit always assumes both backends and still has the older login and profile.

spring: falseFlask only

Single login. Login, navbar and Profile use FlaskSession and FlaskProfile and never call Spring. Spring-only parts like Face ID are left out.

flasksocketflask_runnerspringspring_runner
3 containers · likely Vanilla
spring: trueFlask + Spring

Dual login. SpringSession extends FlaskSession: it does every Flask step, then adds Spring's. A Spring failure never undoes the Flask account.

flasksocketflask_runnerspringspring_runner
5 containers · Education, Business today
Kit choice from the backends its features need to build _config.yml spring: false config.js springEnabled createBackends() { flask, spring|null } spring set null SpringSession adds Spring's steps, never undoes Flask's extends FlaskSession sign up, sign in, logout, current user layouts: site.spring != false leave out Face ID, the gist card, the tracker createSession() picks the class once FlaskProfile ← SpringProfile same pattern for Profile
Only the page starters read springEnabled. Login, the navbar and Profile get one object and never check for Spring themselves.

Mr. Mortensen's three parts, mapped to the kit:

A. Shared code

Login, profile and other shared parts use the spring true/false switch. The kit sets it from the features it turns on.

B. Changing a feature

Add or change backend behaviour by extending a class, like SpringSession extends FlaskSession, instead of if (springEnabled) checks everywhere.

C. Everything else

Each kit gets its own _projects/.makeprojects list, built by Jekyll and make rules. Later, each kit is packed into its own generated repo.

Step 1Bring in upstream login and profileNot started

Import _projects/systems/login and profile with the sync tool (pages #1844, #2004, #2047, all merged). They replace the kit's older copies.

Step 2Tag each feature with its backendsNot started

Add a backends field to catalog.json. spring is on when any feature that is on needs it. Open question: Business has calendar, which uses Spring.

Step 3Write spring from the kitNot started

apply_kit.py writes it into the build. config.js is kit-owned, so its springEnabled line is added by hand once.

Step 4Menu and home page followNot started

Mr. Mortensen's point 2. Spring-only features count as off, so their menu links hide; home page sections get the same check.

Step 5Install only what's neededNot started

The installer skips the spring and spring_runner containers when spring is false.

Step 6Close the gaps upstreamKnown gaps

/signup, /guestlogin, /dm and the student calendar still call Spring with spring: false. Fix upstream, then update.

Step 7Pack each kit into its own repoLater

CI builds each kit with only its features and pushes it to a generated, read-only repo. Development stays in one place.

How to explain it
  • One setting, spring: true or false, decides whether a site needs the Java backend at all.
  • The code picks a class once, Flask or Spring, so pages never have to ask which backend is there.
  • For the kit, that means a smaller Flask-only install, and a clear way to add features by extending a class.

Where the project stands

The project follows an 8-step plan written on October 7 (OCS-Kit-Pages #1). Five steps are done. The two biggest remaining pieces are testing it as an outside school would and finishing the release.

Done 5Partly 2Not started 1
Step 1Lock down the leakMostly done

Leaked credentials and student data removed; history reset. Still to confirm every credential is revoked at its source.

Step 2Strip "us" out of the kitDone

School name, branding, sign-up lock, bios and image metadata scrubbed.

Step 3One settings fileDone

The installer asks the questions and writes the settings.

Step 4One-command setupDone

install.sh / install.bat: browser form, terminal or unattended.

Step 5Easy database setupDone

Tables and the kit's accounts are created on first start.

Step 6Safe code runnerDone

Separate containers, no internet, memory and CPU limits.

Step 7Test it like strangersNot started

Automated tests exist; nobody has installed it as a brand-new school yet.

Step 8Release itPartly

Public, with an install guide and this site. Licenses still missing or mixed.

How to explain it
  • Security came first: leaked keys and student data were removed before anything else.
  • Setup is done: one command, one settings form, automatic database, safe code runner.
  • What's left is proving it works for a stranger, and the licensing and release work.

What has been done

Six weeks from plan to a working, installable kit. Scroll sideways on a phone.

  1. Plan written
  2. v0.1.0: scrubbed copies of pages, flask, spring
  3. Feature catalog, 3 kits, installer, import tool, admin dashboard
  4. Python and Java lessons, install guide, link fixes
  5. Live kit and feature switching; v0.2.0
  6. Images 0.3.0 on Docker Hub
  7. Repos moved to Open-Coding-Society
  8. Lessons fix-up issue closed
  9. First outside contributor PRs
  10. CSA-Admin-OCS forks; upstream Profile classes merged

What comes next

The first three are already moving. The rest are planned, roughly in this order.

Now
Review 4 open pull requests

Game engine fix (Pages #3); Fortune Finders moved under finance-sim with its Spring endpoints back (Pages #4, #5, Spring #1).

Bring the hosted deployment online

Images and a server profile are ready; the kit backends don't answer yet, and this site still points at placeholder backend URLs.

Start the upstream routine

Install the scan workflow and run a catch-up scan. See Keeping up with upstream.

Planned
Flask only or Flask + Spring

Adopt the spring switch and class-based login and profile. See the 7 steps.

Stranger test

Someone outside the team installs a kit from the guide alone.

Licensing and release

One license for all four repos; a release that matches the 0.3.0 images.

Security advisories

A way to tell schools running the kit about security fixes (OCS-Kit-Pages #2).

Finish the leak clean-up

Confirm every leaked credential is revoked; follow up with upstream.

Update links

Docs still point at CSA-Admin-OCS/OCS-Kit-*, which now opens the forks.

Where each repository lives

The kit repos belong to Open-Coding-Society. CSA-Admin-OCS keeps a fork of each, the same way it forks the upstream pages, flask and spring.

Upstreamnone

Installer, feature catalog, sync tool, install guide

UpstreamOpen-Coding-Society/pages

This website and the admin dashboard

UpstreamOpen-Coding-Society/flask

Logins, sections, AI chat proxy, code runner, social

UpstreamOpen-Coding-Society/spring

People, groups, assignments, calendar, hall pass