How do I install the Waaseyaa Site Deploy skill?

Run npx skillmds@latest add jonesrussell/waaseyaa-site-deploy in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Waaseyaa Site Deploy skill do?

Use when creating and deploying a new Waaseyaa framework site to northcloud.one. Covers app scaffold, Caddy config, Deployer, GitHub Actions, server setup, and common pitfalls. It is listed under DevOps & Infra on SkillMD.

Is Waaseyaa Site Deploy safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Waaseyaa Site Deploy?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Waaseyaa Site Deploy free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Waaseyaa Site Deploy?

jonesrussell (@jonesrussell) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Waaseyaa Site Deploy by jonesrussell

Name: Waaseyaa Site Deploy
Author: jonesrussell

Waaseyaa Site Deploy

End-to-end guide for creating and deploying a new site built on the Waaseyaa PHP CMS framework to production on northcloud.one.

When to Use

Creating a new Waaseyaa framework application
Deploying a Waaseyaa site to northcloud.one for the first time
Debugging a failed Waaseyaa deployment
Setting up CI/CD for a Waaseyaa project

Server Facts

Item	Value
Server	`<server-hostname>` (`<server-ip>`)
Web server	Caddy (NOT Nginx)
PHP	8.4, FPM socket at `/run/php/php8.4-fpm.sock`
Deploy user	`<deploy-user>` (has NOPASSWD sudo for caddy and php-fpm reload/restart, and Caddyfile writes)
Admin user	`<admin-user>` (NOPASSWD sudo ALL)
Caddy runs as	`caddy` user, primary group `caddy`. Supplementary groups from `/etc/group` are NOT available under systemd.
Framework repo	`waaseyaa/framework` (public, no PAT needed)
Framework branch for CI	`develop/v1.1` — verify packages exist on this branch before adding deps

Phase 1: App Scaffold

1.1 Create GitHub repo

cd ~/dev && gh repo create waaseyaa/<site-name> --public --description "<description>" --clone
cd ~/dev/<site-name>

1.2 Create .gitignore

/vendor/
/.build/
/.env
*.sqlite
storage/framework/packages.php

1.3 Create composer.json

The Waaseyaa kernel requires the full package stack to boot. There is no lite mode. Use @dev stability (not @alpha) for local path repos.

{
    "name": "waaseyaa/<site-name>",
    "description": "<description>",
    "type": "project",
    "license": "MIT",
    "require": {
        "php": ">=8.4",
        "waaseyaa/access": "^0.1@dev",
        "waaseyaa/admin-surface": "^0.1@dev",
        "waaseyaa/ai-agent": "^0.1@dev",
        "waaseyaa/ai-pipeline": "^0.1@dev",
        "waaseyaa/ai-schema": "^0.1@dev",
        "waaseyaa/ai-vector": "^0.1@dev",
        "waaseyaa/api": "^0.1@dev",
        "waaseyaa/cache": "^0.1@dev",
        "waaseyaa/cli": "^0.1@dev",
        "waaseyaa/config": "^0.1@dev",
        "waaseyaa/database-legacy": "^0.1@dev",
        "waaseyaa/entity": "^0.1@dev",
        "waaseyaa/entity-storage": "^0.1@dev",
        "waaseyaa/field": "^0.1@dev",
        "waaseyaa/foundation": "^0.1@dev",
        "waaseyaa/graphql": "^0.1@dev",
        "waaseyaa/i18n": "^0.1@dev",
        "waaseyaa/mcp": "^0.1@dev",
        "waaseyaa/media": "^0.1@dev",
        "waaseyaa/menu": "^0.1@dev",
        "waaseyaa/node": "^0.1@dev",
        "waaseyaa/note": "^0.1@dev",
        "waaseyaa/path": "^0.1@dev",
        "waaseyaa/plugin": "^0.1@dev",
        "waaseyaa/queue": "^0.1@dev",
        "waaseyaa/routing": "^0.1@dev",
        "waaseyaa/search": "^0.1@dev",
        "waaseyaa/ssr": "^0.1@dev",
        "waaseyaa/state": "^0.1@dev",
        "waaseyaa/taxonomy": "^0.1@dev",
        "waaseyaa/typed-data": "^0.1@dev",
        "waaseyaa/user": "^0.1@dev",
        "waaseyaa/validation": "^0.1@dev",
        "waaseyaa/workflows": "^0.1@dev"
    },
    "repositories": [
        {"type": "path", "url": "../waaseyaa/packages/*"}
    ],
    "autoload": {
        "psr-4": {
            "SiteName\\": "src/"
        }
    },
    "extra": {
        "waaseyaa": {
            "providers": [
                "SiteName\\Provider\\SiteServiceProvider"
            ]
        }
    },
    "config": {
        "optimize-autoloader": true,
        "sort-packages": true
    },
    "minimum-stability": "dev",
    "prefer-stable": true
}

Do NOT add Waaseyaa\Note\NoteServiceProvider to providers — it is auto-discovered from the note package's own composer.json. Adding it manually causes a "type already registered" error.

Before adding a package, verify it exists on the develop/v1.1 branch:

git ls-tree --name-only origin/develop/v1.1 packages/ | sort

If a package only exists on main, use "dev-main" as the version constraint instead of "^0.1@dev".

1.4 Create public/index.php

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

$kernel = new Waaseyaa\Foundation\Kernel\HttpKernel(dirname(__DIR__));
$kernel->handle();

1.5 Create config/waaseyaa.php

Minimal config for a static/marketing site:

<?php

declare(strict_types=1);

return [
    'database' => null,
    'ssr' => [
        'theme' => '',
        'cache_max_age' => 300,
    ],
];

1.6 Create directories and install

mkdir -p storage/framework src/Controller src/Provider templates public/css
composer install

Phase 2: ServiceProvider + Controller

Route registration pattern

<?php

declare(strict_types=1);

namespace SiteName\Provider;

use Waaseyaa\Foundation\ServiceProvider\ServiceProvider;
use Waaseyaa\Routing\RouteBuilder;
use Waaseyaa\Routing\WaaseyaaRouter;

final class SiteServiceProvider extends ServiceProvider
{
    public function register(): void {}

    public function routes(WaaseyaaRouter $router): void
    {
        $router->addRoute(
            'page.home',
            RouteBuilder::create('/')
                ->controller('SiteName\\Controller\\PageController::home')
                ->render()
                ->methods('GET')
                ->build(),
        );
    }
}

Controller pattern

<?php

declare(strict_types=1);

namespace SiteName\Controller;

use Symfony\Component\HttpFoundation\Request as HttpRequest;
use Twig\Environment;
use Waaseyaa\SSR\SsrResponse;

final class PageController
{
    public function __construct(
        private readonly Environment $twig,
    ) {}

    public function home(array $params, array $query, $account, HttpRequest $request): SsrResponse
    {
        return new SsrResponse($this->twig->render('home.html.twig', ['path' => '/']));
    }
}

Local test

rm -f storage/framework/packages.php
REQUEST_METHOD=GET REQUEST_URI=/ SERVER_NAME=localhost php public/index.php

Should output HTML. If it outputs JSON:API errors, check the "Common Pitfalls" section.

Phase 3: Deployment Infrastructure

3.1 Caddyfile

Create Caddyfile in the project root (NOT in ops/nginx/):

# <domain> - included via import in main /etc/caddy/Caddyfile
# Deploy path: ~/<project>, current release: ~/<project>/current

<domain> {
  tls {
    issuer acme {
    }
  }

  root * /home/<deploy-user>/<project>/current/public

  encode gzip zstd

  @css {
    path /css/*
  }
  handle @css {
    header Cache-Control "public, max-age=31536000, immutable"
    file_server
  }

  @js {
    path /js/*
  }
  handle @js {
    header Cache-Control "public, max-age=31536000, immutable"
    file_server
  }

  @images {
    path /img/*
  }
  handle @images {
    header Cache-Control "public, max-age=31536000, immutable"
    file_server
  }

  @ico {
    path *.ico
  }
  handle @ico {
    header Cache-Control "public, max-age=31536000, immutable"
    file_server
  }

  @robots {
    path /robots.txt
  }
  handle @robots {
    header Cache-Control "public, max-age=3600"
    file_server
  }

  file_server
  php_fastcgi * unix//run/php/php8.4-fpm.sock {
    resolve_root_symlink
  }

  log {
    output file /home/<deploy-user>/<project>/log/access.log {
      mode 0644
    }
  }
}

3.2 deploy.php

<?php

namespace Deployer;

require 'recipe/common.php';

set('application', '<project>');
set('keep_releases', 5);
set('allow_anonymous_stats', false);

set('shared_dirs', ['storage']);
set('shared_files', ['.env']);
set('writable_dirs', ['storage', 'storage/framework']);

host('production')
    ->setHostname('<domain>')
    ->set('remote_user', 'deployer')
    ->set('deploy_path', '/home/<deploy-user>/<project>')
    ->set('labels', ['stage' => 'production']);

desc('Upload pre-built release artifact from CI');
task('deploy:upload', function (): void {
    upload('.build/', '{{release_path}}/', [
        'options' => ['--recursive', '--compress'],
    ]);
});

desc('Clear Waaseyaa framework manifest cache');
task('waaseyaa:clear-manifest', function (): void {
    run('rm -f {{release_path}}/storage/framework/packages.php');
});

desc('Reload PHP-FPM to pick up new release');
task('php-fpm:reload', function (): void {
    run('sudo systemctl reload php8.4-fpm');
});

desc('Deploy to production');
task('deploy', [
    'deploy:info',
    'deploy:setup',
    'deploy:lock',
    'deploy:release',
    'deploy:upload',
    'deploy:shared',
    'deploy:writable',
    'waaseyaa:clear-manifest',
    'deploy:symlink',
    'deploy:unlock',
    'deploy:cleanup',
    'php-fpm:reload',
]);

after('deploy:failed', 'deploy:unlock');

If the app has database migrations, add a migrate task before deploy:symlink:

task('waaseyaa:migrate', function (): void {
    run('set -a && . {{deploy_path}}/shared/.env && set +a && php {{release_path}}/bin/migrate');
});

3.3 GitHub Actions workflow

Create .github/workflows/deploy.yml:

name: Deploy Production

on:
  push:
    branches: [main]
  workflow_dispatch:

concurrency:
  group: deploy-production
  cancel-in-progress: false

jobs:
  deploy:
    name: Build & Deploy
    runs-on: ubuntu-latest
    environment: production

    steps:
      - name: Checkout app
        uses: actions/checkout@v4
        with:
          path: app

      - name: Checkout waaseyaa framework
        uses: actions/checkout@v4
        with:
          repository: waaseyaa/framework
          ref: develop/v1.1
          path: waaseyaa

      - name: Set up PHP 8.4
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          extensions: pdo_sqlite, sqlite3, mbstring, xml
          coverage: none

      - name: Install Composer dependencies
        working-directory: app
        run: |
          composer install \
            --no-dev \
            --no-interaction \
            --optimize-autoloader \
            --prefer-dist

      - name: Assemble build artifact
        run: |
          mkdir -p app/.build
          rsync -aL \
            --exclude='.git' \
            --exclude='.build/' \
            --exclude='tests/' \
            --exclude='docs/' \
            --exclude='.env' \
            --exclude='storage/framework/packages.php' \
            --exclude='deploy.php' \
            --exclude='Caddyfile' \
            app/ app/.build/

      - name: Install PHP Deployer
        run: composer global require deployer/deployer --no-interaction

      - name: Set up SSH key
        uses: webfactory/ssh-agent@v0.9.0
        with:
          ssh-private-key: ${{ secrets.DEPLOY_SSH_KEY }}

      - name: Add known host
        run: |
          mkdir -p ~/.ssh
          ssh-keyscan <domain> >> ~/.ssh/known_hosts

      - name: Deploy
        working-directory: app
        run: dep deploy production --no-interaction

Phase 4: Server Setup

Run these steps in order. Use deployer for deploy-related tasks, jones for sudo tasks.

4.1 DNS

Set A records for <domain> and www.<domain> pointing to <server-ip>.

4.2 SSH key

ssh-keygen -t ed25519 -C "<deploy-user>@<domain>" -f ~/.ssh/<project>_deploy -N ""
ssh-copy-id -i ~/.ssh/<project>_deploy.pub <deploy-user>@<server-hostname>

Verify: ssh -i ~/.ssh/<project>_deploy <deploy-user>@<server-hostname> "whoami"

4.3 Server directory structure

ssh -i ~/.ssh/<project>_deploy <deploy-user>@<server-hostname> \
  "mkdir -p /home/<deploy-user>/<project>/{releases,shared/storage/framework,log}"

4.4 Shared .env

ssh -i ~/.ssh/<project>_deploy <deploy-user>@<server-hostname> \
  "cat > /home/<deploy-user>/<project>/shared/.env << 'EOF'
APP_ENV=production
WAASEYAA_DB=/home/<deploy-user>/<project>/shared/storage/waaseyaa.sqlite
EOF"

Create empty database file:

ssh -i ~/.ssh/<project>_deploy <deploy-user>@<server-hostname> \
  "touch /home/<deploy-user>/<project>/shared/storage/waaseyaa.sqlite"

4.5 Caddy log file (CRITICAL)

Caddy runs as the caddy user under systemd. The systemd service does NOT inherit supplementary groups. Caddy cannot create new files in dirs owned by deployer. You must pre-create the log file owned by caddy:

ssh <admin-user>@<server-hostname> \
  "sudo touch /home/<deploy-user>/<project>/log/access.log && \
   sudo chown caddy:caddy /home/<deploy-user>/<project>/log/access.log && \
   sudo chown caddy:caddy /home/<deploy-user>/<project>/log"

4.6 Install Caddyfile

Copy the Caddyfile to the server:

scp -i ~/.ssh/<project>_deploy Caddyfile <deploy-user>@<server-hostname>:/home/<deploy-user>/<project>/Caddyfile

Add the import to the main Caddyfile:

ssh -i ~/.ssh/<project>_deploy <deploy-user>@<server-hostname> \
  "echo 'import /home/<deploy-user>/<project>/Caddyfile' | sudo tee -a /etc/caddy/Caddyfile"

BEFORE reloading, validate ALL Caddyfiles:

ssh -i ~/.ssh/<project>_deploy <deploy-user>@<server-hostname> \
  "caddy validate --config /etc/caddy/Caddyfile 2>&1"

If validation passes, reload:

ssh -i ~/.ssh/<project>_deploy <deploy-user>@<server-hostname> \
  "sudo systemctl reload caddy"

If validation fails, do NOT reload — fix the issue first. A failed reload leaves the old config running, but a failed restart takes ALL sites offline.

4.7 GitHub secrets and environment

gh secret set DEPLOY_SSH_KEY --repo waaseyaa/<site-name> < ~/.ssh/<project>_deploy
gh api repos/waaseyaa/<site-name>/environments/production -X PUT

No WAASEYAA_PAT needed — the framework repo is public.

4.8 Push and verify

git push -u origin main
gh run watch --repo waaseyaa/<site-name>

After deploy succeeds, verify from the server:

ssh -i ~/.ssh/<project>_deploy <deploy-user>@<server-hostname> \
  "curl -sk https://<domain> | grep '<title>'"

Common Pitfalls

Problem	Cause	Fix
`Class "Waaseyaa\Database\PdoDatabase" not found`	Missing `waaseyaa/database-legacy`	Use the full package list — kernel requires everything
`DEFAULT_TYPE_MISSING`	No content type registered	`waaseyaa/note` package auto-discovers `NoteServiceProvider` — just include the package
`Entity type "note" is already registered`	`NoteServiceProvider` listed in both package auto-discovery AND your composer.json providers	Remove it from your providers list
`Source path "../waaseyaa/packages/X" not found`	Package doesn't exist on `develop/v1.1` branch	Check with `git ls-tree origin/develop/v1.1 packages/` — use `"dev-main"` or remove the dep
Caddy reload fails with "permission denied" on log file	`caddy` systemd service can't create files in deployer-owned dirs	Pre-create log file: `sudo touch ... && sudo chown caddy:caddy ...`
Caddy restart takes all sites offline	A Caddyfile in ANY imported site has a syntax error	Always `caddy validate` before reload/restart
`issuer acme {}` syntax error	Empty block on single line	Split to multi-line: `issuer acme {\n }`
App returns JSON:API 500 "failed to boot" via PHP-FPM but works via CLI	Missing `WAASEYAA_DB` in shared `.env`	Add `WAASEYAA_DB=/home/<deploy-user>/<project>/shared/storage/waaseyaa.sqlite`
Committed to wrong repo	Terminal in wrong directory	Always verify `git remote -v` before `git add`
Composer constraint `^0.1@dev` fails for path repo	Package has no `branch-alias` in its composer.json	Use `"dev-main"` as the version constraint

Verification Checklist

After deployment, verify each item:

curl -sk https://<domain> returns HTML (not JSON error)
curl -sk https://<domain>/css/site.css returns CSS (static assets served)
All pages render (check each route)
caddy validate --config /etc/caddy/Caddyfile passes
systemctl is-active caddy returns active
GitHub Actions run shows green
Log file is being written: ls -la /home/<deploy-user>/<project>/log/access.log

Waaseyaa Site Deploy

File contents

Waaseyaa Site Deploy

When to Use

Server Facts

Phase 1: App Scaffold

1.1 Create GitHub repo

1.2 Create .gitignore

1.3 Create composer.json

1.4 Create public/index.php

1.5 Create config/waaseyaa.php

1.6 Create directories and install

Phase 2: ServiceProvider + Controller

Route registration pattern

Controller pattern

Local test

Phase 3: Deployment Infrastructure

3.1 Caddyfile

3.2 deploy.php

3.3 GitHub Actions workflow

Phase 4: Server Setup

4.1 DNS

4.2 SSH key

4.3 Server directory structure

4.4 Shared .env

4.5 Caddy log file (CRITICAL)

4.6 Install Caddyfile

4.7 GitHub secrets and environment

4.8 Push and verify

Common Pitfalls

Verification Checklist

Frequently asked questions

Waaseyaa Site Deploy

File contents

Waaseyaa Site Deploy

When to Use

Server Facts

Phase 1: App Scaffold

1.1 Create GitHub repo

1.2 Create .gitignore

1.3 Create composer.json

1.4 Create public/index.php

1.5 Create config/waaseyaa.php

1.6 Create directories and install

Phase 2: ServiceProvider + Controller

Route registration pattern

Controller pattern

Local test

Phase 3: Deployment Infrastructure

3.1 Caddyfile

3.2 deploy.php

3.3 GitHub Actions workflow

Phase 4: Server Setup

4.1 DNS

4.2 SSH key

4.3 Server directory structure

4.4 Shared .env

4.5 Caddy log file (CRITICAL)

4.6 Install Caddyfile

4.7 GitHub secrets and environment

4.8 Push and verify

Common Pitfalls

Verification Checklist

Related skills

Frequently asked questions

How do I install the Waaseyaa Site Deploy skill?

What does the Waaseyaa Site Deploy skill do?

Is Waaseyaa Site Deploy safe to use?

Which AI agents work with Waaseyaa Site Deploy?

Is Waaseyaa Site Deploy free to use?

Who published Waaseyaa Site Deploy?