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 | | ----------------------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------- | | | analytics.zoo | Web analytics platform powered by Matomo | | | 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