Editing Webapp:Deployment

This guide describes how to deploy code changes and updates to the production Docker stack for WebApp (Laravel + Vue, served via Nginx). The same content is maintained in the WebApp repository as <code>DEPLOYMENT.md</code>; for current status and URLs see <code>DEPLOY-STATUS.md</code> in the repo.

== Overview ==

Production runs as a Docker Compose stack:

* '''app''' – PHP-FPM (Laravel), container name <code>webapp-php</code>

* '''nginx''' – reverse proxy, exposes app on <code>127.0.0.1:8008</code>

* '''db''' – MariaDB 11, data in volume <code>webapp-mysql-data</code>

App code is mounted from the host (<code>/root/WebApp</code>), so many updates only need pull + migrations + frontend build, without rebuilding images.

== Prerequisites ==

* SSH (or direct) access to the server where WebApp runs

* <code>docker</code> and <code>docker compose</code> available

* Repository at <code>/root/WebApp</code> (or adjust paths below)

* <code>.env</code> configured (database credentials, <code>APP_KEY</code>, <code>APP_URL</code>, etc.)

== Deployment Steps ==

=== 1. Go to the app directory ===

<pre class="lang-bash">
cd /root/WebApp
</pre>

=== 2. Pull latest code ===

<pre class="lang-bash">
git pull
</pre>

Resolve any merge conflicts before continuing.

=== 3. Rebuild Docker images (only when needed) ===

Rebuild '''only''' if you changed:

* <code>docker/Dockerfile</code>

* <code>docker-compose.yml</code> (service build context, Dockerfile path, or image name)

* Base PHP/extensions or system packages

<pre class="lang-bash">
docker compose build --no-cache app
docker compose up -d
</pre>

If you did '''not''' change the above, skip this step and keep the stack running.

=== 4. Install or update PHP dependencies ===

<pre class="lang-bash">
docker compose exec -T -u root app composer install --no-interaction
docker compose exec -T -u root app chown -R www:www /var/www/vendor /var/www/bootstrap/cache
</pre>

For major upgrades (e.g. Laravel version bump) you may use <code>composer update</code> instead of <code>composer install</code> after reviewing dependencies.

=== 5. Run database migrations ===

<pre class="lang-bash">
docker compose exec -T app php artisan migrate --force
</pre>

Use <code>--force</code> in production so the command does not prompt.

=== 6. Build frontend assets (Vite) ===

Required after any change to JS, CSS, or Vite config so <code>public/build/</code> is up to date:

<pre class="lang-bash">
docker run --rm -v "$(pwd):/app" -w /app node:20-bookworm-slim sh -c "npm ci && npm run build"
</pre>

Alternatively, build inside the app container and fix ownership:

<pre class="lang-bash">
docker compose exec -u root app sh -c "npm ci && npm run build && chown -R www:www /var/www/node_modules /var/www/public/build"
</pre>

=== 7. Clear application caches ===

<pre class="lang-bash">
docker compose exec -T app php artisan config:clear
docker compose exec -T app php artisan cache:clear
docker compose exec -T app php artisan view:clear
</pre>

Optional after config changes: <code>php artisan config:cache</code>.

=== 8. Restart app (and optionally Nginx) ===

If you only changed code or env (no image rebuild):

<pre class="lang-bash">
docker compose restart app
</pre>

If you changed Nginx config (<code>docker/nginx/conf.d/app.conf</code>):

<pre class="lang-bash">
docker compose restart nginx
</pre>

For a full stack restart:

<pre class="lang-bash">
docker compose up -d
</pre>

== Post-deploy verification ==

* '''Local HTTP check:'''  

  <code>curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8008/</code>  
  Expect <code>200</code>.

* '''Public URLs:'''  

  * https://app.josh.me.uk  

  * https://app.jb-vpn.uk  

* '''Logs:'''  

  <code>docker compose logs -f app</code>  
  <code>docker compose logs -f nginx</code>

== When to run one-time setup again ==

The script <code>docker-setup.sh</code> is for '''initial''' setup (key:generate, migrate, db:seed, passport:install, storage:link). You do '''not''' need to run it on every deploy. Only re-run (or run its steps manually) if:

* You are deploying to a new environment, or

* You have added a step that is not yet in the normal deploy flow (e.g. a new artisan command that must run once).

== Summary: minimal deploy (code-only change) ==

For typical code-only updates (no Dockerfile/compose changes):

<pre class="lang-bash">
cd /root/WebApp
git pull
docker compose exec -T -u root app composer install --no-interaction
docker compose exec -T -u root app chown -R www:www /var/www/vendor /var/www/bootstrap/cache
docker compose exec -T app php artisan migrate --force
docker run --rm -v "$(pwd):/app" -w /app node:20-bookworm-slim sh -c "npm ci && npm run build"
docker compose exec -T app php artisan config:clear && docker compose exec -T app php artisan cache:clear
docker compose restart app
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8008/
</pre>

== Rollback ==

If a deploy causes issues:

# Revert code: <code>git checkout <previous-commit></code> (or <code>git revert</code> and then pull).
# Re-run the same steps (composer install, migrate if you need to reverse migrations separately, npm run build, clear caches, restart app).
# If you had run new migrations, consider <code>php artisan migrate:rollback</code> if appropriate, then redeploy the previous code.

Keep a note of the last known-good commit so you can return to it quickly.

[[Category:Documentation]]
[[Category:Documentation/Webapp]]