Skip to content

Exhibit Development Guide

Jump to bottom
Shumzi edited this page Feb 25, 2026 · 7 revisions

Exhibit Development Guide

This page explains how to develop software for an exhibit at the Jerusalem Science Museum. It covers everything from getting a repository to testing your code on a fresh install.

Getting Your Repository

All exhibit software at the museum must run from a repository in the museum's GitHub organization: jerusalem-science-museum.

There are two ways to set this up:

Option A: Museum creates a repo for you (recommended)

The museum creates a dedicated repository in the org and adds you as a collaborator on that specific repo. You'll have push access to your exhibit repo only — not to any other repos in the organization.

  1. Coordinate with your museum contact to create the repo (see naming convention below)
  2. You'll receive a collaborator invite via email — accept it
  3. Clone the repo and start working
  4. When the project is done, the museum removes your collaborator access

This is the preferred approach because the code lives in the right place from day one.

Option B: Work in your own repo, transfer later

If you prefer to develop privately first:

  1. Create a repo in your own GitHub account
  2. Develop your exhibit there
  3. When done, use GitHub's Transfer repository feature to move it into the jerusalem-science-museum org
  4. The museum will need to accept the transfer on their end

Note: Either way, coordinate with the museum team lead before you start. They'll help you pick the right repo name and set things up.

Repo Naming Convention

Repository names follow the pattern: category-descriptive-name (all lowercase, hyphen-separated).

The first word is the exhibit category — it groups the repo with the rest of that exhibition's code. e.g.:

Prefix Exhibition
space Eitan Stiva Space Exhibition
energy Energy
illusions Illusions

Repo Name Examples:

  • space-what-would-you-take-to-space
  • space-rfid-what-to-take
  • energy-solar-panel-demo

The full list is maintained here. If you need a new category (e.g. for a new exhibition), ask the museum team lead to add it.

The naming convention also helps your repo to be in its respective category in the museum's welcome page

What Your Repo Must Contain

File Purpose Required?
setup.sh Installs exhibit-specific dependencies and configures auto-start. Run once after the base kiosk setup. Yes
run.sh Launches the exhibit. Called automatically on every boot after setup. Yes
requirements.txt Python package dependencies (if your exhibit uses Python) Yes (if Python)
README.md Brief description: what the exhibit does, how to set it up, how to test Yes
.gitignore Exclude .venv/, __pycache__/, logs, data files, etc. Recommended

setup.sh — What It Should Do

Your setup.sh handles exhibit-specific setup only. It does not need to set up the entire machine — that's already done by the base kiosk setup scripts:

Your setup.sh runs after the base setup and should:

  1. Install any additional system packages your exhibit needs via apt
  2. Create a Python virtual environment and install requirements.txt
  3. Set file permissions (chmod +x run.sh)
  4. Configure the exhibit to auto-start on boot

It should be idempotent — safe to run more than once without breaking anything.

Examples

Use these as a starting point for your own setup.sh:

  • Linux Mint — setup.sh: On Mint, the base kiosk setup and the exhibit setup are separate scripts. Your setup.sh handles only exhibit-specific things: venv, pip packages, desktop autostart entry, Chromium kiosk mode, etc.

  • Raspberry Pi — see Kiosk Base Setup RPi: On RPi, the setup script from the wiki page is your repo's setup.sh — you copy it into your repo and customize it (add your apt packages, configure your app). There's no separate base setup step.

Use Claude to help

Writing bash scripts can be tricky. Use Claude (the AI assistant) or any other favourite LLM to help you write your setup.sh and run.sh. Give it one of the example scripts above plus your project's requirements, and ask it to generate a first draft. It's great at this.

run.sh — What It Should Do

run.sh is what executes every time the kiosk boots. Keep it simple:

#!/usr/bin/env bash
cd "$(dirname "${BASH_SOURCE[0]}")"
source .venv/bin/activate
python3 main.py

Key points:

  • Always cd to the script's own directory first (so relative paths work regardless of where it's called from)
  • Activate the virtual environment
  • Launch your application

Platform-specific notes:

  • Linux Mint / browser-based exhibits: run.sh also needs to open Chromium in kiosk mode after the server starts. See the Mint example repo above.
  • Raspberry Pi / hardware exhibits: run.sh might need to launch VLC with hardware decoding flags, or set up serial connections. See the RPi example repo above.

Testing on a Fresh Install - VERY USEFUL!

Your setup.sh must work on a machine that has the base kiosk setup and nothing else. The only way to verify this is to test from scratch.
We recommend testing on a virtual machine on your pc for simplicity. Though, if the exhibit connects to external devices/GPIO pins this is less feasible and might not be worth the trouble.

For Linux Mint exhibits

  1. Install VirtualBox on your development computer
  2. Create a VM and install Linux Mint — see Installing Mint
  3. Run the base kiosk setup script — see Kiosk Base Setup
  4. Clone your exhibit repo and run ./setup.sh
  5. Reboot the VM
  6. Your exhibit should start automatically

For Raspberry Pi exhibits

For faster development iteration, you can use a VM on your computer:

  1. Install VirtualBox on your development computer
  2. Download the Raspberry Pi Desktop ISO (the x86 version for PCs/VMs)
  3. Create a VM and boot from the ISO
  4. Run the base kiosk setup — see Kiosk Base Setup RPi
  5. Clone your exhibit repo and run ./setup.sh
  6. Reboot the VM
  7. Your exhibit should start automatically

Important: The VM is useful for development, but you must also test on an actual Raspberry Pi before submitting. Some things (hardware GPIO, camera, serial devices, GPU acceleration) behave differently on real Pi hardware.

Why this matters

The kiosk computers at the museum start from a fresh OS install. If your setup.sh only works on your development machine — where you manually installed things over weeks — it will fail on a real kiosk. Testing on a fresh install is the only way to catch missing dependencies.

Tips for Getting Started

  • requirements.txt — Generate it with pip freeze > requirements.txt after installing your packages. Commit it to the repo. This is how setup.sh knows what to install.
  • .gitignore — At minimum, ignore .venv/ and __pycache__/. Use gitignore.io to generate one for your tech stack.
  • Don't commit large files — Videos, images, and other large assets shouldn't live in git. Talk to the museum team about where to store them (usually a data/ folder that's downloaded separately).
  • Commit often — Make small, frequent commits with short descriptive messages. It makes it much easier to find and fix problems.
  • Use Claude — Seriously. If you're stuck on bash, dependencies, autostart, or anything else, just ask Claude. It knows these patterns well.

Final Checklist

Before submitting your exhibit, verify:

  • Repo is in the jerusalem-science-museum org (or ready to transfer)
  • Repo name follows the category-descriptive-name convention
  • setup.sh exists and works on a fresh machine after base kiosk setup
  • run.sh exists and launches the exhibit
  • requirements.txt lists all Python dependencies
  • README.md describes the exhibit and setup steps
  • Tested on a fresh Linux Mint VM or fresh Raspberry Pi OS
  • Exhibit starts automatically after reboot

See Also

Home

Kiosk Setup — Linux Mint

  1. Installing Mint
  2. Kiosk Base Setup

Kiosk Setup — Raspberry Pi

Development

Exhibits

Reference

Clone this wiki locally