Try Coop in GitHub Codespaces

Run Coop in your web browser, with nothing to install. GitHub Codespaces gives you a temporary cloud machine running the whole Coop stack, with a demo login and sample data already set up. You won’t need to type any commands.

Use it to look around the UI, show Coop to someone, or check a UI change on a branch.

What you need

• A GitHub account. Codespaces are billed to whoever creates them; see Costs.
• A recent desktop browser: Chrome, Edge, Firefox or Safari.

1. Open it

Click the button above (it’s also on the README). On the next page:

• Branch: leave it on main for the latest version, or pick a branch to try someone’s change. The codespace builds Coop from the branch you pick.
• Machine type: keep 4-core. The 2-core machine doesn’t have enough memory for Coop.
• Click Create codespace.

If you’ve opened one before, GitHub offers to resume it instead of making a new one. That’s quicker, and keeps your earlier data.

2. Wait

A code editor opens in your browser tab, showing this guide. You can ignore the code. In the bottom half of the window, a terminal shows progress:

1. Preparing: the first time, the codespace downloads Coop’s databases and builds Coop. This takes about 10 minutes, or under a minute if the repository has a prebuild ready.
2. Starting the Coop demo: Coop and its databases start, then the demo data is added, with a green ✓ beside each step. This takes 1–3 minutes. The Coop UI may open in a new browser tab during this step, before the demo data is there.
3. Coop is ready: the terminal prints the address of the UI and the demo login.

If the new tab doesn’t appear (browsers sometimes block it), open the Ports tab next to the terminal, find Coop UI (3000), and click the globe icon.

3. Log in

This login only exists inside your codespace.

4. Use it

You’re an admin of Demo Org, which has sample posts, policies and actions, a spam rule that has already acted on some posts, and user reports waiting in a review queue. The demo isn’t connected to a real platform, so actions don’t take anything down.

Things to try:

• Review reports: open Review Console in the left-hand menu, then Start Reviewing on Reported posts. Each job shows the reported post, why it was reported, and what the spam rule already did to it. Pick a decision on the right, choose a policy, and click Submit; the next job opens. Your decisions then appear under Recent Decisions.
• Look at the rule: open Automated Enforcement → Proactive Rules → Remove obvious spam to see its conditions and what it matched.
• Browse the setup: Policies, Actions and Item Types show the demo org’s configuration. Change anything you like; it’s your copy.

The Overview page counts actions up to the start of the current hour, so the rule’s removals show up there within an hour of the codespace starting.

The User Guide covers the rest of the UI.

The UI’s address is private to your GitHub account by default, so sharing the link doesn’t let anyone else in. Keep it that way: if you change the port’s visibility to public in the Ports tab, anyone with the link can log in with the demo password above.

5. Stop it

A codespace stops by itself after a period without activity: 30 minutes, unless you’ve changed your Codespaces settings. Typing in the editor or terminal counts as activity; using the Coop UI tab alone may not. If you’re presenting from the Coop UI tab for a long time, click into the editor tab now and then, or raise the idle timeout in your settings.

To stop it yourself, go to github.com/codespaces, click ⋯ next to the codespace, and choose Stop codespace.

6. Come back

Open github.com/codespaces and click the codespace’s name. The demo starts again on its own, in a minute or two, and keeps your data from last time.

7. Delete it

When you’re done with it, delete it so it stops using your storage: at github.com/codespaces, click ⋯ → Delete. By default, GitHub also deletes codespaces that have been stopped for 30 days.

Costs and time limits

Codespaces are billed to the person who creates them, unless an organization pays for its members’ codespaces (ask your admin).

• Personal GitHub accounts include a free monthly allowance: at least 120 core-hours, which is 30 hours on the 4-core machine Coop uses, and 15 GB of storage. Above that, the 4-core machine costs $0.36 an hour while running.
• A stopped codespace costs nothing per hour but counts towards storage until you delete it.
• Check what you’ve used at github.com/settings/billing.

GitHub’s Codespaces billing page has current prices and limits.

Troubleshooting

The UI tab never opened. Check the terminal: until it says Coop is ready, the UI isn’t up yet. Once it is, open the Ports tab and click the globe icon next to Coop UI (3000). If you see a GitHub sign-in page, sign in with the account that created the codespace.

The login page says the email or password is wrong. Check the terminal said Coop is ready: the demo login is created after Coop starts. If it did, start over.

The review queue or rules are empty. The terminal says Couldn’t add the demo data if that step failed. Open a new terminal (☰ menu → Terminal → New Terminal) and run bash .devcontainer/scripts/start.sh to try again.

The UI shows red error messages. A service may have stopped. Press Ctrl+Shift+P (Cmd+Shift+P on a Mac), type Rebuild Container, and choose Codespaces: Rebuild Container. This restarts the demo and keeps its data.

“This codespace requires a machine with at least 4 cores and 16 GB of RAM”, or no 4-core option. Your account or organization may limit machine types. Ask your organization admin, or create the codespace from a personal account.

The terminal mentions “rate limit” or “toomanyrequests”. Docker Hub, where Coop’s databases come from, limits how often one network address can download without signing in. Wait an hour and rebuild the container (as above), or, if you have a Docker Hub account, add DOCKERHUB_USERNAME and DOCKERHUB_TOKEN (an access token) as Codespaces secrets for the roostorg/coop repository, then rebuild.

The terminal said “The Coop demo didn’t start cleanly”. Rebuild the container as above. If it happens again, start over. If that fails too, run docker compose ps -a in the terminal and share the output with the Coop maintainers in a GitHub issue or on Discord.

A message says the codespace is running in recovery mode. Setting up the codespace failed, often because of a temporary network problem, so it started without Coop. Rebuild the container as above.

I want to start over with fresh demo data. Rebuilding the container keeps the demo’s data. To delete it, open a new terminal (☰ menu → Terminal → New Terminal) and run docker compose down -v && bash .devcontainer/scripts/start.sh.

I closed the progress terminal. Open a new one from the ☰ menu → Terminal → New Terminal, and run bash .devcontainer/scripts/status.sh to see whether the demo is ready.

For engineers

The configuration lives in .devcontainer/: Docker-in-Docker on a 4-core / 16 GB machine, running docker-compose.images.yaml with the docker-compose.codespaces.yaml override, which builds the server, client and migrations images from the checkout. The client’s nginx proxies /api/ to the server, so the browser only talks to the forwarded port 3000. seed-demo.mjs creates the demo login and adds the demo data through Coop’s GraphQL and REST APIs.

• updateContentCommand (prepare.sh) pulls and builds the images; a prebuild runs it ahead of time.
• postStartCommand (start.sh) runs on every start or resume: docker compose up, then the demo data.
• docker compose in the terminal already targets the demo stack, e.g. docker compose ps or docker compose logs -f server.
• To try a code change, rebuild and restart the changed service, e.g. docker compose up -d --build client.

The same configuration works locally with any devcontainer-capable tool, such as VS Code’s Dev Containers extension or the devcontainer CLI:

npx @devcontainers/cli up --workspace-folder .

Running it locally on a host whose kernel lacks legacy iptables support (seen on Linux 7.0), Docker inside the container fails to start with can't initialize iptables table 'nat'. Codespaces machines aren’t affected. To work around it, run sudo update-alternatives --set iptables /usr/sbin/iptables-nft && sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-nft && sudo /usr/local/share/docker-init.sh true in the container, then bash .devcontainer/scripts/start.sh.

The container doesn’t include Node.js or pnpm. For a development setup with hot reload, see Local Development.