Skip to main content
Version: v1 (Current)

Local Dev Setup

This guide walks through the complete setup of the GXP local development environment from a fresh clone to a fully running application. The stack uses Docker Compose to orchestrate a PHP 8.3 Laravel Octane/RoadRunner app server, Horizon queue workers, a Node.js Vite dev server, Nginx with wildcard SSL for local .gxp.test and .eventfinity.test domains, PostgreSQL 16, Redis Stack, and additional services.

Prerequisites​

  • Docker Desktop installed and running (macOS: allocate at least 6 GB RAM, 2 CPUs)
  • Git installed (git --version returns 2.x+)
  • mkcert installed for local SSL certificate generation (brew install mkcert on macOS)
  • Repository access granted (SSH key or HTTPS credentials configured for the GXP repo)
  • Ports available: 80, 443, 3000, 3001, 3478, 5173, 5434, 6006, 6379, 7900, 40000-40099, 50000-50019
  • sudo access to edit /etc/hosts

Step 1: Clone the Repository​

git clone git@github.com:gramercy/gxp.git
cd gxp

If you see Permission denied (publickey), verify your SSH key is added to your GitHub account and loaded in your SSH agent (ssh-add -l).

Step 2: Copy Configuration Files​

cp docker-compose.yaml.example docker-compose.yaml
cp .env.example .env

Verify both files exist:

ls -la docker-compose.yaml .env

If either example file is missing, ensure you are on the correct branch (git checkout master) and have pulled the latest code.

Step 3: Generate Local SSL Certificates​

Install the local CA into your system trust store (one-time operation), then generate wildcard certificates for both domains.

# Install the local CA (only needed once per machine)
mkcert -install

# Create the certs directory
mkdir -p .docker/local/nginx/certs

# Generate wildcard cert for *.gxp.test
mkcert -cert-file .docker/local/nginx/certs/_wildcard.gxp.test.pem \
       -key-file .docker/local/nginx/certs/_wildcard.gxp.test-key.pem \
       "*.gxp.test" "gxp.test"

# Generate wildcard cert for *.eventfinity.test
mkcert -cert-file .docker/local/nginx/certs/_wildcard.eventfinity.test.pem \
       -key-file .docker/local/nginx/certs/_wildcard.eventfinity.test-key.pem \
       "*.eventfinity.test" "eventfinity.test"

Verify all four certificate files exist:

ls .docker/local/nginx/certs/
# _wildcard.eventfinity.test-key.pem
# _wildcard.eventfinity.test.pem
# _wildcard.gxp.test-key.pem
# _wildcard.gxp.test.pem

Step 4: Enable Nginx Site Configurations​

Copy the example configs into the sites-enabled directory:

cp .docker/local/nginx/conf/gxp.test.conf.example \
   .docker/local/nginx/conf/sites-enabled/gxp.test.conf

cp .docker/local/nginx/conf/eventfinity.test.conf.example \
   .docker/local/nginx/conf/sites-enabled/eventfinity.test.conf

cp .docker/local/nginx/conf/mediasoup.conf.example \
   .docker/local/nginx/conf/sites-enabled/mediasoup.conf

cp .docker/local/nginx/conf/turn.conf.example \
   .docker/local/nginx/conf/sites-enabled/turn.conf

If the sites-enabled directory does not exist, create it first: mkdir -p .docker/local/nginx/conf/sites-enabled

Step 5: Add Domains to /etc/hosts​

Add all required local domains to your hosts file (requires sudo):

sudo bash -c 'cat >> /etc/hosts << EOF

# GXP Local Development
127.0.0.1 gxp.test
127.0.0.1 dashboard.gxp.test
127.0.0.1 api.gxp.test
127.0.0.1 assets.gxp.test
127.0.0.1 webhook.gxp.test
127.0.0.1 domain.gxp.test
127.0.0.1 medias.gxp.test
127.0.0.1 turn.gxp.test
127.0.0.1 docs.gxp.test
127.0.0.1 eventfinity.test
127.0.0.1 dashboard.eventfinity.test
127.0.0.1 api.eventfinity.test
127.0.0.1 assets.eventfinity.test
127.0.0.1 webhook.eventfinity.test
127.0.0.1 medias.eventfinity.test
127.0.0.1 turn.eventfinity.test
EOF'

If you already have some of these entries from a previous setup, skip the duplicates.

Step 6: Build and Start Docker Services​

docker compose up -d --build

This may take 5-10 minutes on the first run while Docker builds the images. Subsequent runs will be faster due to layer caching.

Troubleshooting:

  • Port conflicts (e.g., address already in use): Stop the conflicting service (sudo lsof -i :80 to identify it)
  • Build failures on app_build stage: Check Docker Desktop has at least 6 GB memory allocated
  • docker compose not recognized: Ensure Docker Desktop is running and you have Docker Compose V2

Step 7: Install PHP Dependencies​

docker compose exec app composer install

If you see The container name "/ez-app" is not running, wait for the container to finish starting and retry.

Step 8: Install Node.js Dependencies​

The vite container runs npm install automatically on startup, but you can also run it manually:

docker compose exec vite npm install
docker compose exec app php artisan storage:link

Step 10: Run Database Migrations​

docker compose exec app php artisan migrate

If you see Connection refused, the database container may not be ready yet — wait 10-15 seconds and retry.

Step 11: Import Scout Search Indexes​

docker compose exec app php artisan scout:import

If SCOUT_DRIVER=null in your .env (the default for local), this command may have no effect, which is expected.

Step 12: Seed the Database​

docker compose exec app php artisan db:seed

If seeding fails with foreign key constraints, ensure migrations completed successfully. You can start clean with docker compose exec app php artisan migrate:fresh --seed (this drops all tables).

Step 13: Generate Application Key (if needed)​

If the APP_KEY in .env is empty:

docker compose exec app php artisan key:generate

The .env.example ships with a pre-set APP_KEY, so you only need this if you cleared it or want a unique key.

Verification​

After completing all steps, verify the environment is fully operational.

Check All Containers Are Running​

docker compose ps

All containers should show Up status. If any show Restarting or Exited, check their logs:

docker compose logs <service-name> --tail 20

Check Application Responds​

curl -sk -o /dev/null -w "%{http_code}" https://dashboard.gxp.test
# Expected: 200

Check Vite Dev Server​

curl -sk -o /dev/null -w "%{http_code}" https://assets.gxp.test/@vite/client
# Expected: 200

Check Horizon (Queue Workers)​

docker compose exec app php artisan horizon:status
# Expected: Horizon is running.

Access in Browser​

URLPurpose
https://dashboard.gxp.testAdmin Dashboard
https://api.gxp.testAPI endpoint
https://assets.gxp.testVite asset server
https://dashboard.eventfinity.testEventfinity Dashboard
http://localhost:6006Storybook

Success Criteria​

  • All containers are running (docker compose ps shows Up for every service)
  • https://dashboard.gxp.test loads the login page without SSL warnings
  • https://assets.gxp.test proxies to the Vite dev server successfully
  • Horizon is running (horizon:status reports running)
  • Database has been seeded (login with seeded credentials works)