How OCS-in-a-Kit Works
What OCS-in-a-Kit is, how it runs, how it keeps up with upstream pages, the Flask-only plan, and where the project stands.
- What OCS-in-a-Kit is
- Three kits, one codebase
- A running kit
- Turning a feature on or off
- Where the code comes from
- Keeping up with upstream pages
- Flask only or Flask + Spring
- Where the project stands
- What has been done
- What comes next
- Where each repository lives
The Open Coding Society platform with the school taken out, packaged so any school or organization can run its own copy with one command.
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.
Jekyll site on GitHub Pages: lessons, guides, profile, admin dashboard. Repo: OCS-Kit-Pages.
Python API: logins, sections, AI chat proxy, code runner, social. Repo: OCS-Kit-Flask.
Java API: people, groups, assignments, calendar, hall pass. Repo: OCS-Kit-Spring.
One command asks a few questions, writes the settings and starts everything. Repo: OCS-Kit-Vanilla.
- 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.
A simple site you can hand to a student.
A computer science classroom.
An organization serving its own users.
| Feature | Vanilla | Education | Business |
|---|---|---|---|
| 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.
- 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.
- 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.
Four places to change features, from slowest to fastest:
Pick a kit and tick features while installing.
.envKIT=education, FEATURES=+finance-sim. Applies on restart.
_config.ymlkit: name: and features:. Applies on the next site build.
Admin → Manage features. Applies immediately, no restart.
- 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.
- 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.
commits to upstream pages since the last scan
date of the last scan
how often we plan to check from now on
- Monday, automaticScanA workflow compares upstream with the kit and posts a report to one issue.
- Weekly, ~30 minTriageSort every item: update, import or skip.
- One feature per branchBring it inThe sync tool copies it, runs the scrub check and opens a pull request.
- Every pull requestReviewKit tests run; a person checks the pages in each kit.
- Merge, monthly tagShipMerging rebuilds the site. Once a month, tag a release and rebuild images.
The three triage buckets:
Upstream changed a file in a feature the kit already has. update --feature lessons pulls just those changes.
Upstream built something new worth having. import --feature game-engine --paths … brings it in with everything it depends on.
School-specific or personal pages. Add them to exclude in kit.sync.json so they stop showing up.
_config.yml and kits/**, so updates never overwrite them.Show the commands
python3 sync/ocs_kit_sync.py scan --kit ../OCS-Kit-Pages -o sync/reports/pages-scan-$(date +%F).mdpython3 sync/ocs_kit_sync.py update --kit ../OCS-Kit-Pages --feature lessons --prpython3 sync/ocs_kit_sync.py import --kit ../OCS-Kit-Pages --feature game-engine --paths _projects/games/voidstriker --prRun 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.
- 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 onlySingle login. Login, navbar and Profile use FlaskSession and FlaskProfile and never call Spring. Spring-only parts like Face ID are left out.
spring: trueFlask + SpringDual login. SpringSession extends FlaskSession: it does every Flask step, then adds Spring's. A Spring failure never undoes the Flask account.
springEnabled. Login, the navbar and Profile get one object and never check for Spring themselves.Mr. Mortensen's three parts, mapped to the kit:
Login, profile and other shared parts use the spring true/false switch. The kit sets it from the features it turns on.
Add or change backend behaviour by extending a class, like SpringSession extends FlaskSession, instead of if (springEnabled) checks everywhere.
Each kit gets its own _projects/.makeprojects list, built by Jekyll and make rules. Later, each kit is packed into its own generated repo.
Import _projects/systems/login and profile with the sync tool (pages #1844, #2004, #2047, all merged). They replace the kit's older copies.
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.
spring from the kitNot startedapply_kit.py writes it into the build. config.js is kit-owned, so its springEnabled line is added by hand once.
Mr. Mortensen's point 2. Spring-only features count as off, so their menu links hide; home page sections get the same check.
The installer skips the spring and spring_runner containers when spring is false.
/signup, /guestlogin, /dm and the student calendar still call Spring with spring: false. Fix upstream, then update.
CI builds each kit with only its features and pushes it to a generated, read-only repo. Development stays in one place.
- One setting,
spring: trueorfalse, 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.
Leaked credentials and student data removed; history reset. Still to confirm every credential is revoked at its source.
School name, branding, sign-up lock, bios and image metadata scrubbed.
The installer asks the questions and writes the settings.
install.sh / install.bat: browser form, terminal or unattended.
Tables and the kit's accounts are created on first start.
Separate containers, no internet, memory and CPU limits.
Automated tests exist; nobody has installed it as a brand-new school yet.
Public, with an install guide and this site. Licenses still missing or mixed.
- 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.
- Plan written
- v0.1.0: scrubbed copies of pages, flask, spring
- Feature catalog, 3 kits, installer, import tool, admin dashboard
- Python and Java lessons, install guide, link fixes
- Live kit and feature switching; v0.2.0
- Images 0.3.0 on Docker Hub
- Repos moved to Open-Coding-Society
- Lessons fix-up issue closed
- First outside contributor PRs
- 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.
Game engine fix (Pages #3); Fortune Finders moved under finance-sim with its Spring endpoints back (Pages #4, #5, Spring #1).
Images and a server profile are ready; the kit backends don't answer yet, and this site still points at placeholder backend URLs.
Install the scan workflow and run a catch-up scan. See Keeping up with upstream.
Adopt the spring switch and class-based login and profile. See the 7 steps.
Someone outside the team installs a kit from the guide alone.
One license for all four repos; a release that matches the 0.3.0 images.
A way to tell schools running the kit about security fixes (OCS-Kit-Pages #2).
Confirm every leaked credential is revoked; follow up with upstream.
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.
noneInstaller, feature catalog, sync tool, install guide
Open-Coding-Society/pagesThis website and the admin dashboard
Open-Coding-Society/flaskLogins, sections, AI chat proxy, code runner, social
Open-Coding-Society/springPeople, groups, assignments, calendar, hall pass