# Blog Deployment: Existing Staging Server

Project directory: `/var/www/html/002099-wificalls-Backend`

API base: `https://staging-server.worksqr.com/002099-wificalls-Backend/public/api`

This is a procedure, not a record of execution: no remote deployment or
application database change has been performed by the agent.

## 1. Publish and Merge the Code

The local Blog work is currently on `feat/symfony-blog-api` and is not committed
or pushed. On the local development machine, inspect the changes, then stage
only the Blog implementation and its two scoped listener changes:

```bash
git status --short
git add .gitignore composer.json config/routes/blog.yaml docs postman src/Blog src/Controller/Blog tests/Blog
git add src/Command/Blog*.php src/EventListener/BlogApiSubscriber.php src/EventListener/ApiEncryptionListener.php src/EventListener/VonageWebhookNormalizer.php src/Migrations/Version20261104000000.php
git diff --cached --stat
git commit -m "feat: port reference blog CMS to Symfony"
git push -u origin feat/symfony-blog-api
```

Review the staged files before committing. Do not add `.env`, provider keys,
database dumps, `vendor`, or actual authentication credentials.

Merge this branch into `development` through the normal reviewed merge process.
Deploying `development` preserves staging changes made since the feature branch
was created. Do not blindly switch staging to an older feature-branch base.

## 2. Check the Server Runtime and Back Up

On staging:

```bash
cd /var/www/html/002099-wificalls-Backend
git status --short
git branch --show-current
php -v
docker compose ps --services
```

Stop if the worktree is dirty; reconcile those files before pulling. The shown
server is on `development`. Preserve `.env`, `.env.local` if present, existing
uploads, credentials, and all server-only configuration.

Back up the database selected by the existing application and keep the backup
outside the web-accessible project directory. Also preserve the pre-deployment
commit, Composer lock/vendor state, and environment configuration for rollback.

`compose.yaml` alone does not prove the application runs in Docker. Determine
whether Apache/PHP-FPM on the host or a running Compose service executes PHP.
Use that same PHP runtime for Composer, migration, cache, admin, and cron commands.
This project was tested with PHP 7.4 and has legacy PHP constraints. Do not
upgrade Symfony/PHP or bypass platform requirements as part of this deployment.

## 3. Pull the Reviewed Development Branch

Use the existing deployment account and Git credentials. The working tree and
`.git` must be writable by that account. With the server's current www-data
ownership, a www-data Git setup would use:

```bash
sudo -u www-data git fetch origin
sudo -u www-data git pull --ff-only origin development
```

If your existing authenticated Git account is `stagingserver`, use that account
with the appropriate repository write permissions instead. Do not recursively
make the project world-writable or discard server changes. If the fast-forward
pull fails, stop and inspect the branch divergence rather than forcing it.

## 4. Install Existing Dependencies

### Host PHP Runtime

The supplied directory listing shows root-owned `composer.lock` and `vendor`.
If www-data is the deploy/runtime account, give it write access only to these
deployment artifacts before running Composer:

```bash
sudo chown www-data:www-data composer.lock
sudo chown -R www-data:www-data vendor
sudo -u www-data mkdir -p var/cache/composer
sudo -u www-data env COMPOSER_HOME=/var/www/html/002099-wificalls-Backend/var/cache/composer php7.4 /usr/local/bin/composer install --prefer-dist --optimize-autoloader --no-scripts --no-interaction
```

Replace `php7.4` and `/usr/local/bin/composer` only with the actual compatible
runtime and Composer executable on your server (`command -v composer`).
Blog encryption now uses the app's existing OpenSSL cryptor; no additional
encryption dependency or targeted package update is required.
Do not run an unrestricted `composer update`. Do not run Composer as root or
use `--ignore-platform-reqs`. Retain dev dependencies if the existing staging
application uses `APP_ENV=dev`; `--no-dev` can remove bundles it needs.

### Docker PHP Runtime

Do not use the host PHP/Composer commands if the application runs in a container.
Substitute the PHP service name reported by `docker compose ps --services` and
its actual in-container project root:

```bash
docker compose exec -T --workdir CONTAINER_PROJECT_ROOT PHP_SERVICE php -v
docker compose exec -T --workdir CONTAINER_PROJECT_ROOT PHP_SERVICE composer install --prefer-dist --optimize-autoloader --no-scripts --no-interaction
```

Use the same `docker compose exec ...` prefix for each following PHP command.
Confirm whether the image bundles code/vendor or bind-mounts them: image-based
deployments must rebuild using the project's existing Docker deployment process;
an install in a disposable container layer is not a persistent deployment.
Do not invent a service name, run a second stack, or change the existing mounts.

## 5. Add Blog Environment Values

Keep existing `APP_ENV`, `DATABASE_URL`, provider credentials, app encryption,
and other environment values unchanged. A Git branch named `development` does
not imply that the application uses `APP_ENV=dev`.

Edit the existing untracked environment configuration with appropriate privileges
(the listing shows `.env` is root-owned). Add only the Blog values below. If
`.env.local`, container-injected variables, or a dumped `.env.local.php` is used,
update that authoritative configuration through the existing deployment process.

```dotenv
BLOG_PUBLIC_URL=https://staging-server.worksqr.com/002099-wificalls-Backend/public
BLOG_PREVIEW_TOKEN_SECRET=REPLACE_WITH_NEW_RANDOM_SIGNING_SECRET
BLOG_ADMIN_TOKEN_HOURS=168
BLOG_MEDIA_DISK=s3
BLOG_MEDIA_MAX_UPLOAD_MB=10
BLOG_SITE_URL=
BLOG_SITE_REVALIDATE_SECRET=
```

Generate the preview signing secret using `openssl rand -hex 32`. No separate
Blog encryption password is needed: public responses and crypto tools reuse the
current environment's existing `API_ENCRYPTION_*` settings through
`OpenSslApiCryptor`. Do not change those settings during this deployment or
distribute actual secrets through shared docs/Postman collections. S3 reuses the existing
AWS configuration and `CLOUDFRONT_DOMAIN`; make sure those are available inside
the actual PHP runtime. Set `BLOG_MEDIA_PUBLIC_URL` explicitly if needed.

For local-media testing instead, replace `BLOG_MEDIA_DISK=s3` with `local` and add:

```dotenv
BLOG_MEDIA_PUBLIC_URL=https://staging-server.worksqr.com/002099-wificalls-Backend/public/uploads
```

Blank site/revalidation values prevent calls to a website during the initial
smoke test. Set them later to the actual website origin and its bearer secret.
For a separate browser CMS, restrict `BLOG_ALLOWED_ORIGINS` to its actual origin
when known. Do not include the backend URL's subdirectory in a CORS origin.

Create runtime directories for a host www-data installation:

```bash
sudo install -d -o www-data -g www-data -m 0750 var/cache/blog-rate-limits
sudo install -d -o www-data -g www-data -m 0755 public/uploads/blog/media
```

For Docker, apply equivalent ownership using the container PHP user's numeric
UID/GID and mapped directories, not an assumed host UID. Uploaded files must be
served as static media, with PHP execution disabled in the upload location.

## 6. Apply Only the Blog Migration

Use the existing app environment and verify its database before applying this.
For host PHP with www-data, run:

```bash
sudo -u www-data php7.4 bin/console doctrine:migrations:execute 'DoctrineMigrations\Version20261104000000' --up --dry-run
sudo -u www-data php7.4 bin/console doctrine:migrations:execute 'DoctrineMigrations\Version20261104000000' --up --no-interaction
sudo -u www-data php7.4 bin/console cache:clear --no-debug
sudo -u www-data php7.4 bin/console debug:router wsqr_blogPosts --no-debug
sudo -u www-data php7.4 bin/console blog:create-admin blog-admin@example.com 'Blog Administrator'
```

The admin command prompts interactively for a password. For Docker use an
interactive `docker compose exec` (without `-T`) when creating the admin.
Ensure CLI and web PHP receive the same `APP_ENV` and settings. If PHP-FPM or
Docker injects environment variables, use the existing service reload/recreate
procedure to pick up new values. Do not blindly reload unrelated services.

This migration creates 13 new `blog_*` tables; no existing business tables are
altered. It also records the version in Doctrine metadata. Do not import
`docs/sql/blog-cms.mysql.sql` in addition to running this migration, and do not
run all pending migrations or `doctrine:schema:update`.

## 7. Test the Deployed URLs

Check the public endpoint:

```bash
curl -i 'https://staging-server.worksqr.com/002099-wificalls-Backend/public/api/v1/posts'
```

Expected: HTTP 200, `Content-Type: application/json`, header
`X-Blog-Encryption: aes-256-cbc`, and a raw Base64 encrypted body. Use the app's
existing AES decryptor before parsing JSON. An encryption failure returns 503,
not plaintext article data. Admin API requests remain plain JSON over HTTPS
with Blog bearer authentication.

Import `postman/WifiCalls-Blog-CMS.postman_collection.json` and set local values:

```text
baseUrl = https://staging-server.worksqr.com/002099-wificalls-Backend/public/api
adminEmail = blog-admin@example.com
adminPassword = the password entered above
```

Run Login, Current admin, Create draft, and Public list. Draft must be hidden.
Publish the disposable post with:

```http
POST {{baseUrl}}/admin/blogs/{{postId}}/publish
Authorization: Bearer {{adminToken}}
```

Then fetch public list/detail and run the collection's administrator-only
decrypt request to inspect the result. Test media upload and open its URL.
Finally smoke-test the existing mobile login, calls, recording and SMS flows
on staging. Local regression checks are not evidence of live provider behavior.
Do not run the collection's import/write/delete requests against real content.

## 8. Add the Scheduler

For a host PHP installation, add through `sudo crontab -u www-data -e`:

```cron
* * * * * cd /var/www/html/002099-wificalls-Backend && /usr/bin/php7.4 bin/console blog:publish-scheduled --no-debug >> var/log/blog-cron.log 2>&1
* * * * * cd /var/www/html/002099-wificalls-Backend && /usr/bin/php7.4 bin/console blog:refresh-cache --no-debug >> var/log/blog-cron.log 2>&1
```

Verify the PHP binary path first. For Docker, use the existing container
scheduler mechanism, working directory, and environment instead of host PHP.
Cache delivery is a no-op until the website URL and revalidation secret are set.

## Rollback

Restore the previously captured application release and its compatible
lock/vendor state using the normal deployment procedure, then clear its cache.
Leave the new Blog tables intact to preserve content. Do not run the migration
down against staging content or revert environment/provider settings blindly.
