# Code Online — deployment and use

## What changed
The Groups/My Group/Group Management Overview navigation entry now opens Code Online in all role workspaces. HODs also have Code Online. Group Project Assignment and existing group records are retained for coursework; no group data is deleted.

The workspace has a local Ace syntax-highlighting editor, automatic indentation, language/runtime selectors, up to eight source files, a primary entry file, standard input, optional program arguments, compile/run output, error status and elapsed time. Drafts are stored in this browser per signed-in user and language. Import/download works on the current file. This is a batch runner, not an interactive terminal or a web-app hosting service.

## Languages and public access
On 15 October 2026, GET https://emkc.org/api/v2/piston/runtimes returned 87 runtime versions representing 84 distinct language names. Aliases are not counted as extra languages. The workspace always reads the actual runtime list from the configured service; the count is not hard-coded. A new self-hosted instance has no runtimes until they are installed.

The supplied example executes C 10.2.0 only because those values are fixed. The new UI sends the language/version selected by the user. Availability of a runtime does not imply access to extra libraries, GUI programs or network connections.

A real anonymous execution test against the public URL returned HTTP 401 with a whitelist-only message. Piston's current official documentation says public execution requires authorization. The default endpoint can list runtimes without being authorized to execute. Configure approved access or run your own instance before expecting programs to execute.

## Apply to an existing SLPS installation
1. Back up the project, deploy the complete updated slps folder and preserve production settings/uploads. No new database migration is needed; the existing auth_rate_limits table is used.
2. Configure PISTON_API_URL on the PHP server. It is a base URL ending before /runtimes or /execute:
   - Public: https://emkc.org/api/v2/piston
   - Private instance example: http://127.0.0.1:2000/api/v2
3. If the provider requires a token, set PISTON_API_TOKEN only on the server. PISTON_AUTH_HEADER defaults to Authorization and PISTON_AUTH_PREFIX defaults to `Bearer ` (including the space). Set these to the exact header/scheme supplied by your provider. An IP-whitelisted endpoint may not need a token.
4. Plain HTTP is rejected unless PISTON_ALLOW_HTTP=1 is explicitly configured for a trusted private runner. HTTPS certificate verification stays enabled. Browser requests cannot supply or change the runner URL or token.
5. See config/piston-apache.example.conf for Apache SetEnv examples. The sample is not loaded automatically. Apply it to your VirtualHost or supported environment mechanism and reload the PHP/web server. For Docker, set the same variables on the PHP service; for PHP-FPM, use its environment settings.
6. Enable PHP cURL (preferred). A verified TLS HTTP-stream fallback is provided when allow_url_fopen is enabled. Ensure the PHP server can reach the configured runner and that private storage is writable for the short-lived runtime cache.
7. Press Ctrl+F5 and open Code Online. Refresh languages, select C/Python or another installed runtime, load an example and run it. If listing works but running reports unauthorized, execution access still needs configuration.

## Self-hosted Piston
Use an isolated Linux machine suitable for the Piston sandbox and follow the official project instructions for Docker/cgroup requirements. Keep the runner management API private to your application network rather than exposing it publicly.

Official setup starting point:

```
git clone https://github.com/engineer-man/piston
cd piston
docker compose up -d api
cd cli
npm ci
cd ..
node cli/index.js ppman list
node cli/index.js ppman install python
```

Use the package list to install the other runtimes you want. Check GET /api/v2/runtimes on that instance, then configure its base URL in SLPS. If PHP is in a different container, use the runner service's reachable hostname instead of 127.0.0.1.

Official references:
- https://github.com/engineer-man/piston#public-api
- https://github.com/engineer-man/piston#installation
- https://github.com/engineer-man/piston#api

## Running code
Choose a language and installed version. The first source tab is the entry point; use names such as Main.java for a public Java class Main. Add supporting files with + File. Enter all scanf/input/Scanner data in Standard input before choosing Run code. Optional arguments must be a JSON array of strings, for example ["first", "second"]. Ctrl/Cmd+Enter also runs the current workspace.

Compilation and execution results are separate: compiler errors still appear when no run result exists. Program output is rendered as plain text. A service failure replaces the previous console content so old output is not mistaken for a new result.

## Limits and storage
- Authentication and CSRF are required for execution.
- 10 runs per minute per account; 128 KB source total; 32 KB stdin; eight files; 20 short program arguments.
- Compile and run wall/CPU budgets: 10 seconds and 3 seconds. The Piston service enforces sandbox resource policies; PHP never executes student source locally.
- Response size and displayed output are capped. Large/continuous output should be reduced.
- Runtime discovery is cached for five minutes. Browser drafts are local to the device/account and are not server backups. Download work you want to keep separately.

## Validation performed
Real public runtime discovery confirmed 84 languages/87 versions. An anonymous public C execution request confirmed HTTP 401, so successful execution against that public service could not be verified without authorization.

The PHP proxy and browser were tested against a controlled Piston-compatible HTTP fixture using an isolated SLPS PHP/MariaDB setup. Tests covered authentication/CSRF, runtime validation, filename checks, server-only authorization headers, stdin, compile errors, timeout responses, denied access, safe output rendering, rate limits, Ace editing, file tabs, language drafts/reload persistence, and responsive sharp-corner layouts. This fixture validates the integration contract; it is not a substitute for testing real compilation on your authorized or self-hosted runner.
