Freegle Platform

This is the monorepo for Iznik, the platform for Freegle, an online reuse network.

Directory	What it is
iznik-nuxt3/	Nuxt frontend — user site (ilovefreegle.org) and moderator tools (modtools.org)
iznik-server-go/	Go API (v2) — the primary API
iznik-batch/	Laravel batch processing — digests, notifications, scheduled tasks
status-nuxt/	Development status dashboard and test runner
iznik-nuxt3/android/, ios/	Capacitor mobile apps (Android/iOS), built from the same Nuxt code

Installation

Installation

git clone https://github.com/Freegle/Iznik

On Windows, Docker Desktop works but is unusably slow. We use WSL2 instead:

1. Install a WSL2 distribution (Ubuntu recommended). For a dedicated install: wsl --install --name freegle
2. Clone this repository from your IDE using a WSL2 path (e.g., \\wsl$\Ubuntu\home\edward\FreegleDockerWSL).
3. Install Docker
4. Open a WSL2 terminal in the repository directory.
5. Start Docker: sudo service docker start

Windows hosts file

Add these to your hosts file:

127.0.0.1 freegle.localhost
127.0.0.1 freegle-dev.localhost
127.0.0.1 freegle-prod.localhost
127.0.0.1 modtools-dev.localhost
127.0.0.1 modtools-prod.localhost
127.0.0.1 phpmyadmin.localhost
127.0.0.1 mailpit.localhost
127.0.0.1 tusd.localhost
127.0.0.1 status.localhost
127.0.0.1 apiv2.localhost
127.0.0.1 delivery.localhost

Configuration

Copy .env.example to .env and modify as needed. The basic system works without configuration, but some features require API keys (Google OAuth and so on) — see .env.example for the full list.

After configuration changes, rebuild:

docker-compose build --no-cache

Running

Running

docker-compose up -d

File syncing to Docker containers happens automatically via the host-scripts container.

Monitor startup progress at http://status.localhost:8081.

The system builds in stages:

1. Infrastructure (databases, queues, reverse proxy) — ~2-3 minutes
2. Development tools (PhpMyAdmin, Mailpit) — ~1 minute
3. Freegle components (websites, APIs) — ~10-15 minutes

Main applications

Service	URL	Login
Freegle Dev	https://freegle-dev.localhost	[email protected] / freegle
Freegle Prod	https://freegle-prod.localhost	[email protected] / freegle
ModTools Dev	https://modtools-dev.localhost	[email protected] / freegle
ModTools Prod	https://modtools-prod.localhost	[email protected] / freegle

Dev containers reload on first view (normal Nuxt dev mode behaviour). Prod containers run production builds.

Development tools

Tool	URL
Status Monitor	http://status.localhost:8081
PhpMyAdmin	https://phpmyadmin.localhost
Mailpit	https://mailpit.localhost
Traefik Dashboard	http://localhost:8080
API v2 (Go)	https://apiv2.localhost:8192

Lightweight setup (limited resources)

Run just the frontend against live production APIs:

docker compose --profile dev-live up -d freegle-dev-live

Access at http://localhost:3004. Changes to iznik-nuxt3/ files sync automatically.

Warning: Actions in this container affect real Freegle data.

Container management

docker logs freegle-freegle-dev       # View logs
docker exec -it freegle-percona mysql -u root -piznik  # Database access
docker restart freegle-status         # Restart a service

Rebuild from scratch

docker compose down
docker system prune -a
docker compose up -d

Testing

Testing

Tests run from the status page at http://status.localhost:8081:

• Go tests for iznik-server-go (v2 API)
• Laravel tests for iznik-batch (batch processing)
• Vitest unit tests for iznik-nuxt3 (frontend stores and components)
• Playwright end-to-end tests for the user-facing site

Test data

The system contains one test group, FreeglePlayground, centred around Edinburgh. The recognised postcode is EH3 6SS.

CI/CD

CI/CD

CircleCI runs the full test suite on every push to master. On success, master is auto-merged to the production branch, which triggers Netlify deployments for both ilovefreegle.org and modtools.org.

Mobile app builds (Android/iOS) run on the production branch via Fastlane, with weekly promotion from beta to production.

Worktrees

Worktrees

Multiple isolated development environments can run in parallel using git worktrees. Each worktree gets its own Docker Compose stack on unique ports.

./freegle worktree create feature-x    # Create isolated environment
./freegle status                       # See all worktrees and URLs
./freegle worktree remove feature-x    # Cleanup

See ./docs/developers/reference/worktrees.md for details.