The Zoo

The Zoo is a simulated web environment. It's meant to be complex enough for true end-to-end testing (like the live web), while being reproducible (unlike the live web).

Web services are hosted on the .zoo domain accessible through a forward proxy.

Prerequisites

Docker, Docker Compose, NodeJS are required to run the Zoo. Make sure you have the latest version of each installed on the host machine.

Installation

npm install
npm start

For install/start issues, see here.

Core Services

• Squid Proxy (Port 3128) - HTTP proxy for host browser access
• CoreDNS - DNS server for all containers in the environment, resolves .zoo domains (domains are specified in docker-compose or based on file path).
• Caddy - Reverse proxy and static file server. Also handles SSL, with private keys committed for reproducibility.
• PostgreSQL - Resets database state on container restart
• MySQL - Resets database state on container restart
• Redis - Key-value store
• Stalwart - Mail server (GitHub)
• Hydra - OAuth2/OpenID Connect server (Ory Hydra)

Sites

• Apps - Located in sites/apps/, each directory is a .zoo domain
• Static Sites - Located in sites/static/, served directly by Caddy

Setup instructions for manual browsing

In the main repo you can use npm run browse to open a configured playwright instance (make sure you've installed playwright by running npx playwright install-deps && npx playwright install first).

However, it's better to just customize a normal Firefox profile to manually browse.

1. Create a brand new profile (about:profiles, or in Nightly use the profile selector)
2. Type about:support in the address bar and show the profile folder
3. Copy/paste docs/firefox-profile/user.js into the profiler folder. This has conveniences like recoginizing .zoo as a valid domain suffix.
4. about:preferences#privacy -> Certificates -> View Certificates -> Import. Select core/caddy/root.crt from the project. Check "Trust this CA to identify websites".
5. Restart Firefox (about:profiles -> Restart Normally)
6. Configure the Zoo proxy: about:preferences#general -> Network Settings -> Settings... -> Configure Proxy Access to the Internet -> Manual Proxy Configuration -> HTTP (HTTPS) Proxy "localhost" -> Port(s) "3128".

Auth.zoo Users

Test user credentials are available in scripts/seed-data/personas.ts

Available Sites

Applications Gallery

Screenshot	Site	Description
	auth.zoo	auth.zoo
	classifieds.zoo	Classified ads marketplace from VisualWebArena
	example.zoo	example.zoo
	excalidraw.zoo	Virtual whiteboard for sketching diagrams
	focalboard.zoo	Open source project management and kanban boards
	gitea.zoo	Self-hosted Git service with web interface
	home.zoo	home.zoo
	miniflux.zoo	Minimalist feed reader with RSS/Atom support
	misc.zoo	Miscellaneous utilities and test endpoints
	northwind.zoo	Northwind sample database with phpMyAdmin interface
	onestopshop.zoo	E-commerce shopping site from VisualWebArena
	paste.zoo	Self-hosted pastebin
	performance.zoo	Performance testing and monitoring tools
	postmill.zoo	Reddit-like forum and link aggregator from VisualWebArena
	snappymail.zoo	Modern webmail client with clean interface
	wiki.zoo	Offline Wikipedia reader and knowledge base

Troubleshooting

Upon setting up the Zoo on different host machines, two issues where identified that can be fixed by extending the Docker daemon configuration. First, create the /etc/docker/daemon.json file (if it does not already exist).

Error	Fix
cache export is not supported for the docker driver. switch to a different driver, or turn on the containerd image store, and try again.	You can enable the containerd image store by adding the "containerd-snapshotter": true attribute to daemon.json
wget: unable to resolve host address ‘dl-cdn.alpinelinux.org’	You can configure Docker to use an alternative DNS server by adding the "dns": ["8.8.8.8", "1.1.1.1"] attribute to daemon.json

If you've run into both issues and you've attempted to resolve both, your docker.json should look like this:

{
  "features": {
    "containerd-snapshotter": true
  },
  "dns": ["8.8.8.8", "1.1.1.1"]
}

Finally, restart Docker:

sudo systemctl restart docker