Setup Guide

Two ways to run Wave Networks: Docker for development, or shared hosting for production.

Requirements

Docker Setup (Development)

1. Clone both repos as siblings

   git clone git@github.com:WaveNetworks/wave-networks-core.git admin
   git clone git@github.com:WaveNetworks/child-app.git child-app

   Keep child-app/ intact as a reference template — you'll copy it in the next step.

2. Copy the template into your own app folder

   cp -r child-app my-app
   cd my-app
   rm -rf .git
   git init
   git remote add origin git@github.com:YourOrg/my-app.git

   This gives you a clean copy to build on. The original child-app/ stays untouched as a working reference you can diff against, pull updates from, or consult when you need to see how a pattern was implemented.

3. Configure your app

   cp .env.example .env
   # Edit .env with your values (see config reference below)

   Rename all child_app_ prefixes in docker-compose.yml to your app name (e.g., myapp_admin_main, myapp_main, myapp_shard_1).

4. Start Docker

   docker compose up -d

   This starts 8 services: PHP-Apache app, 3 admin databases (main + 2 shards), 3 child databases, and Mailhog for email testing.

5. Build the theme

   cd my-app
   npm install && npm run build:css

   The template ships SCSS source only — no compiled CSS. This step compiles the glassmorphism theme to assets/css/custom.css. Without it, you'll see plain Bootstrap.

6. Run the installers

   Visit http://localhost/admin/install/index.php to set up admin core and create the first admin user.

   Visit http://localhost/my-app/install/index.php to set up your child app.

   Use the explicit /index.php path — the directory URL may return 403 depending on your Apache config.

   Migrations run automatically on first page load after config is created.

7. Start building

   Source code is mounted read-only — edit PHP files locally, refresh the browser. Docker cannot modify your working directory. Mailhog runs at http://localhost:8025.

Running Multiple Apps (Docker)

Each child app gets its own complete, isolated Docker stack — including its own admin databases, its own admin install, and its own branding. Every database and volume is namespaced by the child app name so multiple stacks never collide.

1. Namespace databases and volumes

All databases and volumes are prefixed with your app's directory name (hyphens → underscores). When you clone child-app as payments, rename every child_app_ prefix to payments_ in docker-compose.yml:

Do NOT use external: true — each stack must own its volumes.

2. Unique ports

Change the host port mapping in docker-compose.yml:

3. Filesystem isolation

Source code is mounted read-only (:ro). Docker cannot modify your working directory. Writable paths use named volumes (vendor dependencies, uploaded files, databases).

4. Fresh admin per stack

Each stack runs its own admin install with independent users, settings, and branding. The admin installer creates the first admin user during setup.

Shared Hosting Setup (Production)

1. Generate vendor dependencies locally

   cd admin
   composer install --no-dev

2. Copy the template and upload to your webroot

   Copy child-app/ to your own folder, then upload admin/ and your app to public_html/:

   cp -r child-app my-app
   cd my-app && rm -rf .git && git init
   # Upload via SFTP, or use the included deploy script:
   cp deploy_config.sample.py deploy_config.py
   # Edit with your SFTP credentials
   python deploy.py --all

   Keep child-app/ locally as a reference — you don't need to deploy it to production.

3. Create databases

   Create 6 databases via cPanel or phpMyAdmin:

   # Admin core
   wncore_main
   wncore_shard_1
   wncore_shard_2
   
   # Your child app
   yourapp_main
   yourapp_shard_1
   yourapp_shard_2

4. Create the files directory

   mkdir -p /home/username/files/home
   chmod 755 /home/username/files

   This must be outside public_html/ — not web-accessible.

5. Run the installers

   Visit https://yourdomain.com/admin/install/index.php — enter your database credentials and create the first admin user.

   Visit https://yourdomain.com/your-app/install/index.php — enter your child app DB credentials.

   The installers write config/config.php and lock themselves down after completion.

6. Set up cron

   * * * * * /usr/bin/php /home/username/public_html/admin/cron/cron.php > /dev/null 2>&1

   This processes the email queue and runs scheduled tasks every minute.

Configuration Reference

Core Settings

SMTP Settings

Optional Services

Deploy Script

Both repos include a Python SFTP deployment script (deploy.py) that uploads only changed files:

# Deploy files changed in last commit
python deploy.py

# Deploy all tracked files + vendor
python deploy.py --all

# Preview what would be uploaded
python deploy.py --dry-run

Create deploy_config.py from the sample:

SFTP_HOST = "your-server.example.com"
SFTP_PORT = 22
SFTP_USER = "username"
SFTP_PASS = "password"
LOCAL_ROOT = r"/path/to/local/admin"
REMOTE_ROOT = "admin"    # relative to SFTP root

The script compares file sizes before uploading and skips unchanged files automatically.

Additional Flags

# Include specific files or directories (even untracked)
python deploy.py --include vendor/ assets/css/custom.css

# Deploy only vendor/ directory (after composer install)
python deploy.py --vendor

# Child-app only: skip CSS build check
python deploy.py --no-css-check

The child-app deploy script warns if assets/css/custom.css hasn't been built. Run npm install && npm run build:css before deploying.

Production Deploy Checklist

Follow this order when deploying to a new server. Admin must be deployed and installed before the child app, and the child app's CSS must be built before the website will display correctly.

1. Pre-flight
   • Verify server has PHP 8.2+ with pdo_mysql, gd, mbstring extensions
   • Create databases: admin main + N shards, child app main + N shards
   • Create ../files/ directory above public_html (or let the installer auto-create it)
2. Deploy admin (first)

   cd admin
   composer install --no-dev
   cp deploy_config.sample.py deploy_config.py
   # Edit deploy_config.py with SFTP credentials
   python deploy.py --all
   python deploy.py --vendor

3. Install admin

   Visit https://yourdomain.com/admin/install/index.php

   • Step 1: Configure databases (1–20 shards), file storage path (auto-detected), SMTP
   • Step 2: Create first admin user (email + password)
4. Deploy child app (second)

   cd my-app
   npm install && npm run build:css
   cp deploy_config.sample.py deploy_config.py
   # Edit deploy_config.py with SFTP credentials
   python deploy.py --all

5. Install child app

   Visit https://yourdomain.com/my-app/install/index.php — enter child app DB credentials.

6. Deploy website (third)

   Upload site/, index.php, .htaccess, sitemap.xml, and root files via SFTP.

7. Post-deploy
   • Set up cron: * * * * * /usr/bin/php public_html/admin/cron/cron.php
   • Configure branding in admin settings (logo, favicon, site name, theme color)
   • Verify all three components load correctly in browser