# glsl-sandbox: A Self-Hosted GLSL Editor and Gallery

> glsl-sandbox is a Go-backed web application for publishing and administering GLSL shader examples. It combines a browser-based editor and gallery with SQLite data, thumbnails, template reloads, and an administrative interface.

**mrdoob/glsl-sandbox** — Shader editor and gallery.

- Repository: https://github.com/mrdoob/glsl-sandbox
- Website: https://glslsandbox.com/
- Stars: 1,687 · Forks: 280
- Language: JavaScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/mrdoob-glsl-sandbox

## What glsl-sandbox Organizes for Shader Authors

glsl-sandbox addresses the problem of publishing a collection of GLSL examples through a web application rather than maintaining an ad hoc set of static pages. Its public-facing component is a gallery, while the application also provides a shader editor context and an administrative page for managing displayed effects. The repository description calls it a "Shader editor and gallery," and the README documents separate gallery and admin paths at `/` and `/admin`.

The intended users are people who want to host shader work behind their own server and need a simple presentation layer for effects. The server stores effect records and thumbnail files, then renders them through a shared template. This is a different operating model from using the hosted glslsandbox.com service. A self-hosted instance gives the operator control over the binary, data directory, templates, and static assets, but it also makes database migration, backups, and process supervision the operator's responsibility.

The project does not document a production deployment guide, authentication policy, rollback procedure, or multi-tenant permission model. Its documented setup is compact, which makes it more approachable for a small personal collection than for a large editorial system. The first server start creates an admin user and prints its credentials, but the README does not describe password rotation, account recovery, or the exact authentication flow after startup.

## Go Server, SQLite Data, and Template Rendering

The server is a Go program built from `./server/cmd/glslsandbox`. The module declares Go `1.24.0` and specifies toolchain `go1.24.2`, so the documented build path requires a compatible Go installation. Dependencies include Echo for the HTTP layer, `sqlx` for database access, the Bun SQLite driver, JWT support, environment configuration, and cryptographic packages.

The default data directory is `./data`. According to the README, this directory contains the SQLite database named `glslsandbox.db` and a `thumbs` directory. `DATA_PATH` changes the data location. The data model passed to the template represents each gallery effect with an ID, version, thumbnail image name, and hidden flag. It also carries pagination state and an `Admin` boolean that distinguishes the gallery from the administrative path.

Rendering uses one Go template for both pages: `server/assets/gallery.html`. The server reloads templates and assets on each query, which makes local edits visible after a page reload without restarting the process. The README identifies `server/assets/css` as the source for `/css` and `server/assets/js` as the source for `/js`. This design keeps the page surface small, but it also means that operators must understand the relationship between asset directories, URLs, and the shared template.

The application is not limited to a static gallery. The documented `Hidden` field indicates that effects can be moderated, while the admin flag changes the page context. The README does not describe the editor's shader compilation contract, supported WebGL versions, or error-reporting behavior, so those details cannot be assumed from the repository description.

## Local Build and First Gallery Visit

The README documents a local development path that starts by cloning a fork. Replace the repository placeholder with the reader's own GitHub account and create a feature branch:

```bash
$ git clone git@github.com:<your user>/glsl-sandbox
$ cd glsl-sandbox
$ git checkout -b <feature name>
```

The server also needs test data for a useful local gallery. Download and extract the archive in the repository directory:

```bash
$ curl -O https://downloads.zooloo.org/glslsandbox-data.tar.gz
$ tar xvf glslsandbox-data.tar.gz
```

Build the server with the Go compiler, then start it:

```bash
$ go build ./server/cmd/glslsandbox
$ ./glslsandbox
```

On its first start, the server creates an admin user and prints the credentials. The public application should then be available at `http://localhost:8888`, with administration at `http://localhost:8888/admin`. The README does not provide a shader source example or a documented button sequence for creating the first effect, so the first verifiable action is opening those pages after the data archive and binary are in place.

For development, assets and templates are read on each query. After changing `server/assets/gallery.html`, `server/assets/css`, or `server/assets/js`, reload the page and inspect the change. That behavior is convenient for small edits, although the README does not describe cache invalidation beyond this reload behavior.

## Docker Compose Persistence and Port Mapping

The repository includes `docker-compose.yml` for a containerized server. It uses the published image `ghcr.io/jfontan/glsl-sandbox:latest`, stores a host-mounted `./data` directory at `/data`, and maps host port `3000` to container port `8888`. The `Dockerfile` builds the Go server with the `cgosqlite` build tag, copies the repository into the runtime image, exposes ports `8888` and `8883`, and starts `/glslsandbox/entrypoint.sh`.

The README does not explicitly give this command, so the repository file documents the configuration but not a supported command for starting it. The concrete configuration to inspect is:

```yaml
services:
 glslsandbox:
 image: ghcr.io/jfontan/glsl-sandbox:latest
 volumes:
 -./data:/data
 ports:
 - "3000:8888"
```

Because the container port is `8888` and the host mapping is `3000`, a user following the Compose file should expect the host-side endpoint to differ from the binary's documented `localhost:8888` endpoint. The README does not explain the separate port `8883`, so its purpose should not be inferred. The Compose file also does not pin an image digest, which means the `latest` tag can resolve to a different image over time.

## Maintenance Signals, Licensing, and Upgrade Boundaries

The repository is not archived. Its last push was on 2026-08-25, which is a recent maintenance signal under the available repository facts. Recent releases include `v0.1.41` on 2024-04-20, `v0.1.40` on 2024-01-08, and `v0.1.39` on 2023-12-26. The release sequence is documented, but the README does not explain compatibility guarantees between releases or provide a database migration command.

The repository identifies its license as MIT. That permits broad use under the terms of the license, but operators still need to preserve the license text and review the actual `LICENSE` file for their distribution. The license does not by itself answer questions about hosted content, shader authorship, thumbnails, or third-party dependencies.

Upgrade cost is tied to a small Go binary plus a mutable data directory. The documented data consists of `glslsandbox.db` and thumbnails, yet no backup, restore, schema migration, or rollback procedure appears in the README. Template and asset reloads make development changes easy to inspect, but they do not provide release tracking. Before replacing a binary, an operator would need to preserve the data directory and confirm how the new server version expects to find it.

## Limits of the glsl-sandbox Server Model

The clearest limitation is the narrow documentation around editorial and operational controls. The data structure exposes `Hidden`, `Page`, `IsPrevious`, `IsNext`, `Admin`, and effect metadata, but the README does not explain moderation actions, version history, deletion, bulk operations, or recovery. That matters for an editor or gallery operator because a simple gallery page does not establish a complete content-management workflow.

A second limitation is the deployment boundary. The server can be started locally with `./glslsandbox` or placed behind Docker Compose, but the README does not describe reverse proxy settings, TLS termination, health checks, backups, or scheduled upgrades. Port `8883` is exposed by the Dockerfile without a documented purpose. This makes the repository more suitable as a codebase to inspect and extend than as a complete production operations package.

The alternative is a hosted gallery at `glslsandbox.com`. That approach removes the need to run the Go binary, initialize SQLite, persist thumbnails, or expose an admin route, but it gives less control over the server, data directory, templates, and assets. A static, manually maintained gallery is another alternative for read-only collections. It avoids server administration and database state, but it does not provide the documented admin page, moderation flag, pagination data, or template reload behavior. The choice depends on whether live administration matters more than operational simplicity.

## Conclusion

Adopt glsl-sandbox when you need a small, self-hosted GLSL gallery with an editor and moderation interface. Do not choose it if you need documented rollback, multi-user permissions, or a deployment process beyond the README's local server and Docker Compose setup. First verify that the Go version, SQLite data layout, and public gallery behavior match your deployment requirements.

## FAQ

### How do I install and run glsl-sandbox locally?

Clone the repository, download and extract the test data, then build with `go build ./server/cmd/glslsandbox` and run `./glslsandbox`. The README says the server is available at `http://localhost:8888` and the admin interface is at `http://localhost:8888/admin`.

### Where does glsl-sandbox store its database and thumbnails?

By default, data is read from `./data`. The directory contains `glslsandbox.db` and the `thumbs` directory. Set `DATA_PATH` to use another location, for example `DATA_PATH=/my/data/directory ./glslsandbox`.

### Does glsl-sandbox support Docker Compose?

The repository includes `docker-compose.yml`. It defines the `ghcr.io/jfontan/glsl-sandbox:latest` image, mounts `./data` at `/data`, and maps host port `3000` to container port `8888`. The README does not document a specific startup command.

## Sources

- [License: MIT](https://github.com/mrdoob/glsl-sandbox/blob/master/LICENSE)
- [mrdoob/glsl-sandbox on GitHub](https://github.com/mrdoob/glsl-sandbox)
- [Project website](https://glslsandbox.com/)
- [README](https://github.com/mrdoob/glsl-sandbox/blob/master/README.md)
- [Releases](https://github.com/mrdoob/glsl-sandbox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mrdoob-glsl-sandbox