Skip to main content

Local Environment Setup

Our local development environment is called Zoo and is located in the zoo project. It provides a complete Docker-based development stack for the entire Publica.la platform.

Prerequisites​

  • macOS running on Apple Silicon (M1/M2/M3)
  • OrbStack for Docker container management
  • At least 16GB RAM (8GB will be dedicated to SingleStore)
  • At least 50GB free disk space
  • mkcert for SSL certificates (brew install mkcert nss)

Quick Start​

  1. Clone the Zoo repository

    git clone git@gitlab.com:publicala/zoo.git
    cd zoo

    Note: We use SSH for cloning. Ensure you have an SSH key configured in your GitLab profile.

  2. Run the automated setup

    ./release-animals.sh

    This interactive script will:

    • Install SSL certificates
    • Clone all project repositories
    • Set up common configuration files
    • Build Docker containers
    • Initialize databases
    • Create storage buckets
    • Install project dependencies

  3. Start developing

    zoo up    # Start all containers
    zoo down  # Stop containers when done

For command reference, see the Zoo README.

Architecture Overview​

Zoo uses Docker Compose to orchestrate multiple services that mirror our production environment:

Core Services​

  • Nginx: Reverse proxy handling SSL and routing to services
  • SingleStore: Distributed SQL database (8GB RAM allocated)
  • Valkey: Redis-compatible caching layer
  • MinIO: S3-compatible object storage

Application Containers​

All containers run Alpine Linux with development tools pre-installed:

  • farfalla: Core platform backend (Laravel PHP)
  • castoro: PDF processing service
  • coniglio: Event tracking and analytics
  • medusa: Content intake automation
  • volpe: Digital reader (Node.js)
  • micelio: Smart CDN proxy
  • criceto: Testing toolkit

Network Architecture​

  • All services communicate via Docker network zoo_default
  • Services accessible via .localhost domains (e.g., farfalla.localhost)
  • SSL certificates automatically generated for all domains
  • Nginx handles routing based on domain names

Development Features​

PHP-SPX Profiler​

All PHP containers include PHP-SPX, a powerful profiling tool for performance analysis.

Using PHP-SPX​

  1. Access the SPX UI: Append ?SPX_UI_URI=/ to any URL

    https://farfalla.localhost/?SPX_UI_URI=/

  2. Enable profiling:

    • Check the "Enabled" checkbox in the SPX UI
    • Once enabled, navigate normally and SPX will collect profiles automatically
    • Each page load creates a new profile entry

  3. Understanding the interface:

    • Flat profile: Shows time spent in each function
    • Flame graph: Visualizes call stack and execution time
    • Timeline: Shows execution over time
    • Click any function to see details and call hierarchy
    • Select different profiles from the dropdown to compare performance

  4. Profiling best practices:

    • Profile specific endpoints, not entire page loads
    • Run multiple times to ensure consistent results
    • Focus on functions with high exclusive time
    • Look for unexpected deep call stacks

  5. Managing profile data:

    # View stored profiles
    zex farfalla ls -la /tmp/spx

    # Clear all profiles in all containers
    zoo spx:clear

    # Clear profiles in specific container
    zoo spx:clear --project=farfalla

  6. When to clear profiles:

    • Before starting a new profiling session
    • When /tmp/spx gets too large
    • After completing performance optimization work

Container Access​

Access any container's shell using zin:

zin farfalla  # Enter farfalla container
zin           # Enter current project's container (when in project directory)

Command Execution​

Run commands in containers using zex:

zex composer install           # In current project
zex farfalla composer install  # In specific container
zex yarn build                 # Node.js commands work too

Database Access​

Connect to SingleStore:

  • Host: 127.0.0.1
  • Port: 3306
  • User: root
  • Password: 12345678

Use TablePlus or any MySQL client for GUI access.

Object Storage​

MinIO console available at http://localhost:9001:

  • User: minioadmin
  • Password: minioadmin

Initial Project Setup​

After running release-animals.sh, each project needs minimal configuration:

Environment Configuration​

Each project requires a .env file for environment-specific configuration. The release-animals.sh script does not create these files automatically. You will need to create a .env file for each project by copying the corresponding .env.example file.

For example, to configure the farfalla project, you would:

cp farfalla/.env.example farfalla/.env

You can find an example of the .env file for the farfalla project here.

After creating the .env file, you may need to adjust the values to match your local setup.

Laravel Projects (farfalla, medusa, coniglio, etc.)​

  1. Environment is pre-configured via .env
  2. Dependencies are installed automatically
  3. Migrations run during setup

Node.js Projects (volpe, micelio)​

  1. Environment is pre-configured
  2. Dependencies installed via yarn install
  3. Start dev server: zex yarn dev

Next Steps​

  • Review Zoo README for command reference
  • Set up your IDE for remote development
  • Explore the codebase structure
  • Join #dev-environment on Slack for support
X

Graph View