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 DEPLOYMENT.md; for current status and URLs see DEPLOY-STATUS.md in the repo.

Overview

Production runs as a Docker Compose stack:

app – PHP-FPM (Laravel), container name webapp-php

nginx – reverse proxy, exposes app on 127.0.0.1:8008

db – MariaDB 11, data in volume webapp-mysql-data

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

Prerequisites

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

docker and docker compose available

Repository at /root/WebApp (or adjust paths below)

.env configured (database credentials, APP_KEY, APP_URL, etc.)

Deployment Steps

1. Go to the app directory

cd /root/WebApp

2. Pull latest code

git pull

Resolve any merge conflicts before continuing.

3. Rebuild Docker images (only when needed)

Rebuild only if you changed:

docker/Dockerfile

docker-compose.yml (service build context, Dockerfile path, or image name)

Base PHP/extensions or system packages

docker compose build --no-cache app
docker compose up -d

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

4. Install or update PHP dependencies

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

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

5. Run database migrations

docker compose exec -T app php artisan migrate --force

Use --force in production so the command does not prompt.

6. Build frontend assets (Vite)

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

docker run --rm -v "$(pwd):/app" -w /app node:20-bookworm-slim sh -c "npm ci && npm run build"

Alternatively, build inside the app container and fix ownership:

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"

7. Clear application caches

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

Optional after config changes: php artisan config:cache.

8. Restart app (and optionally Nginx)

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

docker compose restart app

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

docker compose restart nginx

For a full stack restart:

docker compose up -d

Post-deploy verification

Local HTTP check:

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

Public URLs:

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

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

Logs:

 docker compose logs -f app  
 docker compose logs -f nginx

When to run one-time setup again

The script docker-setup.sh 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):

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/

Rollback

If a deploy causes issues:

Revert code: git checkout <previous-commit> (or git revert 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 php artisan migrate:rollback if appropriate, then redeploy the previous code.

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