# Deploying the iDealers website

For the developer or hosting technician who puts this site live. You do not need to have seen the project before; everything you need is here or linked from here.

The site replaces the WordPress/Elementor site at https://idealers.net. It is a Laravel 13 application with a Filament admin panel at `/admin`. Visitors only ever get server-rendered HTML, CSS, JavaScript and media; there are no forms on the site itself (the three forms are iframes from `idealers.app`) and no payments (six Stripe payment links).

> **Action needed regardless of this migration: the live TLS certificate is wrong.**
> On 2026-11-17 `openssl s_client -connect idealers.net:443 -servername idealers.net` showed a certificate whose subject and subjectAltName are only `autoconfig.idealers.net` (issued 2026-11-08). Browsers reject it for `idealers.net`, so visitors currently see a security warning and search engines may fail to crawl the site. The host's certificate (normally Let's Encrypt through the control panel or certbot) must be reissued for `idealers.net` and `www.idealers.net`. Fix this now on the WordPress hosting; the new server needs a correct certificate before cut-over in any case (step 6 below).

---

## 1. Server requirements

| Item | Requirement |
|---|---|
| PHP | 8.3 or newer (developed on 8.5). CLI and FPM/Apache module the same version. |
| PHP extensions | `bcmath`, `ctype`, `curl`, `dom`, `fileinfo`, `filter`, `gd` (image handling in the admin), `intl` (Filament), `mbstring`, `openssl`, `pdo`, `pdo_mysql`, `session`, `tokenizer`, `xml`, `zip`, `zlib`. Recommended: `opcache` enabled. |
| Database | MySQL 8.0+ or MariaDB 10.6+ (utf8mb4). A single empty database and a user with full rights on it. |
| Web server | nginx 1.20+ with PHP-FPM, or Apache 2.4 with `mod_rewrite` and `AllowOverride All` (the project ships `public/.htaccess`). |
| Document root | **must be the `public/` folder**, never the project folder. Everything else (`.env`, `storage/`, `reference/`, `scripts/`, `vendor/`) must not be reachable from the web. |
| Composer | 2.x, on the server or on the machine that builds the release. |
| Node.js | 20+ with npm, only to build CSS/JS (`npm run build`). Not needed on the server if you build elsewhere and upload `public/build/`. |
| Disk | About 300 MB for code + vendor; media in `public/media/` (copied from the old uploads) plus admin uploads. |
| Cron | One cron entry for the Laravel scheduler (section 5). |
| Outgoing mail | SMTP account, used only for admin password-reset e-mails. |

Shared hosting works if it lets you point the domain's document root at `public/` and run `php artisan` over SSH. If the panel forces `public_html` as root, put the project one level up and make `public_html` a symlink to `project/public` (do not move `index.php` out of `public/`).

## 2. Production `.env`

Copy `.env.example` to `.env` and fill it in. `.env.example` already holds production defaults with comments; the values that must be set or checked:

```dotenv
APP_ENV=production
APP_DEBUG=false                 # never true in production
APP_URL=https://idealers.net
APP_KEY=                        # php artisan key:generate --force (once; keep it, it encrypts sessions)

SITE_CANONICAL_URL=https://idealers.net
SITE_NOINDEX=false              # true on a staging copy only

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=idealers
DB_USERNAME=idealers
DB_PASSWORD=...                 # strong, unique

SESSION_DRIVER=database
SESSION_SECURE_COOKIE=true
CACHE_STORE=file
QUEUE_CONNECTION=database       # see section 5; nothing is queued today

MAIL_MAILER=smtp
MAIL_HOST=...  MAIL_PORT=587  MAIL_USERNAME=...  MAIL_PASSWORD=...
MAIL_FROM_ADDRESS="info@idealers.net"

ADMIN_PATH=admin                # optional: a less guessable path; then update the web server notes below
ADMIN_2FA_REQUIRED=true

SECURITY_FORCE_HTTPS=true
SECURITY_HSTS=true              # leave SUBDOMAINS/PRELOAD false unless every subdomain has HTTPS
TRUSTED_PROXIES=                # set if behind Cloudflare or a load balancer

LOG_LEVEL=warning
```

Analytics IDs (`SITE_GA4_ID`, `SITE_GTM_ID`, verification codes) can be set here or, better, by the owner in the admin under **Site settings** (the admin value wins). The old WordPress site used Google tag `GT-5R7TZF6M` (through Google Site Kit), Meta Pixel `263970003369260` and Hotjar `3840705`; confirm with the owner which ones to keep. Nothing loads before a visitor accepts cookies.

Never commit `.env` or copy it between environments without changing `APP_KEY` consciously (changing it logs everyone out).

## 3. Database: from SQLite (development) to MySQL/MariaDB

Development uses `database/database.sqlite`. Production uses MySQL/MariaDB. The migrations (`database/migrations/`) create: `users` (with admin flag and two-factor columns), `password_reset_tokens`, `sessions`, `cache`, `cache_locks`, `jobs`, `job_batches`, `failed_jobs`, and the content tables `content_values`, `page_meta`, `settings`, `redirects`, `media`, `activity_log`. A fresh migrate on an empty database was tested (see `docs/QA_REPORT.md`).

**Fresh start (normal case).** The page content defaults live in `resources/content/*.php`, so an empty database already shows the full site.

```bash
mysql -u root -p -e "CREATE DATABASE idealers CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  CREATE USER 'idealers'@'localhost' IDENTIFIED BY 'STRONG-PASSWORD';
  GRANT ALL PRIVILEGES ON idealers.* TO 'idealers'@'localhost'; FLUSH PRIVILEGES;"
php artisan migrate --force
php artisan site:create-admin
php artisan site:media-sync
```

**Carrying over edits made on a staging/dev copy.** There is no export/import command. Only the tables `content_values`, `page_meta`, `settings`, `redirects`, `media` (and `users` if wanted) hold owner data. Run `php artisan migrate --force` on MySQL first, then export those tables from the old database as data-only inserts (for SQLite: `sqlite3 database/database.sqlite ".mode insert content_values" "select * from content_values;"`, one table at a time) and import them. Copy uploaded files in `public/media/uploads/` along with them. Then `php artisan optimize:clear`. Activity log and sessions do not need to move.

## 4. Build and deploy

Order of operations for the first deploy (later deploys skip steps 6 and 7):

1. Build the release (on the server or in CI):

   ```bash
   # copy the project to /var/www/idealers/releases/2026-xx-xx
   cd /var/www/idealers/releases/2026-xx-xx
   composer install --no-dev --optimize-autoloader --no-interaction
   npm ci && npm run build              # produces public/build/; or upload a build made elsewhere
   rm -rf reference node_modules tests scripts   # build-time material; never deployed or served
   ```
2. Link the shared, persistent parts (they must survive releases):

   ```bash
   ln -sfn /var/www/idealers/shared/.env .env
   rm -rf storage && ln -s /var/www/idealers/shared/storage storage          # logs, sessions, cache
   mkdir -p /var/www/idealers/shared/media-uploads
   ln -sfn /var/www/idealers/shared/media-uploads public/media/uploads       # admin uploads live here
   ```
   Admin uploads are written to `public/media/uploads/Y/m/` and served as `/media/uploads/...`. Without the shared link they would be lost with the next release.
3. `php artisan migrate --force`, then **`php artisan site:images`**. It writes AVIF/WebP variants of every image in `public/media` to `public/media/_v/` and the manifest `public/media/_v/manifest.json`, which the site reads to serve `<picture>`. It is incremental (unchanged images are skipped, so normally it takes a second or two) and safe on every deploy. The variants of the shipped images come with the release; `_v/` is part of the release, not the shared folder, so this step recreates the variants of admin uploads in each new release (an upload also gets its variants immediately when it is uploaded). Until it has run, images simply load in their original format. `--force` regenerates everything (about 2 minutes); `--limit=N` processes in batches. Needs PHP GD with AVIF and WebP (`php -r "print_r(gd_info());"`).
4. `php artisan optimize` (caches config, routes, views, events), `php artisan filament:optimize`, and **`php artisan cache:clear`**. The full-page cache keeps whole HTML pages, which name the CSS/JS files of the build they were made with; `npm run build` replaces those files, so pages cached before the deploy would load without styles until the cache is cleared. (The cache is only cleared automatically when content is saved in the admin.)
5. Switch the web server to the new release (`ln -sfn releases/2026-xx-xx /var/www/idealers/current`) and reload PHP-FPM so OPcache picks up the new code (`systemctl reload php8.5-fpm`, or the version installed).
6. First deploy only: `php artisan site:create-admin` (section 6).
7. First deploy only: `php artisan site:media-sync` registers the existing `public/media` images and videos in the admin's media library (safe to re-run).
8. Run the post-deploy checks (section 10).

PHP limits for admin uploads (images up to 5 MB, videos up to 50 MB): in php.ini (or the FPM pool) set `upload_max_filesize = 55M` and `post_max_size = 55M` (development PHP defaults are 2M/8M, so larger uploads fail before reaching the application), `memory_limit = 256M`, and `expose_php = Off`. The web server must accept the same size (`client_max_body_size 60m` in nginx; `LimitRequestBody` unset or at least 60 MB in Apache).

What must never be web-reachable or deployed: `reference/` (old WordPress HTML/CSS), `scripts/`, `tests/`, `docs/`, `.env`, `storage/`, `vendor/`, `node_modules/`. With the document root at `public/` only `public/` is served (`reference/` sits outside `public/`; `/reference/html/home.html` returns 404 locally, checked by `scripts/qa/seo-smoke.php`); deleting it in step 1 makes sure it is not on the server at all.

Updating later: repeat the release build; content edited in the admin is in the database and survives deploys, uploads are in the shared folder. The full-page cache is cleared automatically on every admin save; after every deploy run `php artisan migrate --force`, `php artisan site:images` (step 3), `php artisan optimize` **and** `php artisan cache:clear` (step 4).

### Web server configuration (nginx)

From Backend 2. Adjust the PHP-FPM socket and certificate paths.

```nginx
# HTTP and www -> https://idealers.net
server {
    listen 80;
    listen [::]:80;
    server_name idealers.net www.idealers.net;
    return 301 https://idealers.net$request_uri;
}
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name www.idealers.net;
    ssl_certificate     /etc/letsencrypt/live/idealers.net/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/idealers.net/privkey.pem;
    return 301 https://idealers.net$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name idealers.net;

    root /var/www/idealers/current/public;     # document root = public/ ONLY
    index index.php;
    charset utf-8;
    server_tokens off;
    client_max_body_size 60m;          # admin video uploads (ADMIN_MAX_VIDEO_KB) + margin

    ssl_certificate     /etc/letsencrypt/live/idealers.net/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/idealers.net/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    gzip on;
    gzip_vary on;
    gzip_comp_level 5;
    gzip_types text/plain text/css text/xml application/xml application/javascript text/javascript application/json application/ld+json image/svg+xml application/manifest+json;
    # brotli on; brotli_types ...same list...   (if ngx_brotli is installed)

    # Dotfiles (except /.well-known) and sensitive file types
    location ~ /\.(?!well-known/) { deny all; return 404; }
    location ~* \.(bak|backup|old|orig|save|swp|sql|sqlite|db|log|ini|env|sh|lock|dist|ya?ml|md|phar|zip|tar|gz|7z)$ { deny all; return 404; }

    # Trailing-slash canonical URLs (WordPress style): /about -> /about/
    location ~ ^/(?!admin|livewire|filament|build/|media/|fonts/|js/|css/|storage/|vendor/|up$|\.well-known/|wp-)[^.]*[^/]$ {
        if ($request_method ~ ^(GET|HEAD)$) { return 301 $uri/$is_args$args; }
        try_files $uri /index.php?$query_string;
    }

    # Long-lived caching for hashed build output and media; nothing under /media is ever executed
    location ^~ /build/ { expires 1y; add_header Cache-Control "public, max-age=31536000, immutable"; add_header X-Content-Type-Options nosniff; try_files $uri =404; }
    location ^~ /media/ { expires 1y; add_header Cache-Control "public, max-age=31536000, immutable"; add_header X-Content-Type-Options nosniff; try_files $uri @laravel; }
    location ^~ /fonts/ { expires 30d; add_header Cache-Control "public, max-age=2592000"; add_header Access-Control-Allow-Origin "*"; try_files $uri =404; }

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    location @laravel { rewrite ^ /index.php last; }

    # Only the front controller is executed
    location = /index.php {
        fastcgi_pass unix:/run/php/php8.5-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }
    # Any other .php URL (/wp-login.php, /xmlrpc.php...) is never executed: Laravel answers 410 Gone.
    location ~ \.php$ { rewrite ^ /index.php last; }

    error_log  /var/log/nginx/idealers.error.log warn;
    access_log /var/log/nginx/idealers.access.log;
}
```

If `ADMIN_PATH` is changed from `admin`, change `admin` in the trailing-slash location above (and in `public/.htaccess`) to the new path.

Behind Cloudflare or a load balancer: set `TRUSTED_PROXIES` to the proxy IPs (otherwise HTTPS detection, per-IP rate limiting and HSTS do not work), and do not let the CDN cache HTML longer than the origin's `Cache-Control: no-cache, private` (each HTML response carries a unique CSP nonce). `/build/*` and `/media/*` can be cached forever.

### Web server configuration (Apache)

- Virtual host `DocumentRoot /var/www/idealers/current/public` with `AllowOverride All`. The shipped `public/.htaccess` needs `mod_rewrite` and the `FileInfo`, `Options` and `Indexes` overrides; it uses `mod_headers`, `mod_expires`, `mod_deflate` and optionally `mod_brotli` when present. It refuses every `.php` other than `index.php`, dotfiles, backups and config files, and adds the `/about` -> `/about/` redirect.
- `public/media/.htaccess` switches off script execution under `/media` (including admin uploads).
- `ServerTokens Prod` and `ServerSignature Off` in the main config, `expose_php = Off` in php.ini.
- HTTP -> HTTPS and www -> apex are also done by the application in production (`SECURITY_FORCE_HTTPS`, `SECURITY_FORCE_CANONICAL_HOST`), but doing it in the vhost saves a PHP request:

  ```apache
  <VirtualHost *:80>
      ServerName idealers.net
      ServerAlias www.idealers.net
      Redirect permanent / https://idealers.net/
  </VirtualHost>
  ```

**Shared hosting where the document root cannot point at `public/`.** Put this `.htaccess` in the project root (next to `artisan`) so nothing outside `public/` is reachable. Prefer a real `DocumentRoot .../public` whenever possible.

```apache
Options -Indexes
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(\.env|\.git|storage|vendor|reference|database|app|config|bootstrap|resources|routes|tests|scripts|docs|node_modules)(/|$) - [F,L,NC]
    RewriteCond %{REQUEST_URI} !^/public/
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>
<FilesMatch "^(\.env.*|composer\.(json|lock)|package(-lock)?\.json|artisan|phpunit\.xml|vite\.config\.js|.*\.md)$">
    Require all denied
</FilesMatch>
```

## 5. Scheduler and queue

- **Scheduler:** no scheduled task exists (checked `routes/console.php`, `bootstrap/app.php`, `app/Console`). A cron line is harmless and future-proof: `* * * * * cd /var/www/idealers/current && php artisan schedule:run >> /dev/null 2>&1`. Expired admin sessions in the `sessions` table are cleaned by Laravel's built-in lottery.
- **Queue:** nothing is queued. `QUEUE_CONNECTION=database` is a safe default; no worker is needed.

## 6. First admin user

```bash
php artisan site:create-admin                  # asks for name, e-mail and password
php artisan site:create-admin --name="Owner" --email=owner@idealers.net   # password prompted securely
php artisan site:create-admin --email=owner@idealers.net --update          # reset password / grant admin
```

There is no default account and no password in any seeder. With `ADMIN_2FA_REQUIRED=true` (the `.env.example` value) the owner must set up an authenticator app at first login. Give the owner `docs/ADMIN_GUIDE.md`.

## 7. File permissions

The PHP process user (for example `www-data`) needs write access to `storage/`, `bootstrap/cache/` and `public/media/uploads/` (the shared uploads folder) only; everything else read-only.

```bash
chown -R deploy:www-data /var/www/idealers/releases/2026-xx-xx /var/www/idealers/shared
find /var/www/idealers/releases/2026-xx-xx -type d -exec chmod 755 {} \;
find /var/www/idealers/releases/2026-xx-xx -type f -exec chmod 644 {} \;
chmod -R ug+rwX /var/www/idealers/shared/storage /var/www/idealers/shared/media-uploads bootstrap/cache
chmod 640 /var/www/idealers/shared/.env
```

## 8. Backups

| What | How | How often |
|---|---|---|
| Database | `mysqldump --single-transaction --routines idealers \| gzip > idealers-$(date +%F).sql.gz` | Daily, keep 30 days, copy off the server |
| Uploaded files | the shared `media-uploads` folder (= `public/media/uploads/`) (rsync or host snapshots) | Daily |
| `.env` | Store a copy in the password manager (it holds `APP_KEY` and DB/SMTP passwords) | On every change |
| Code | The release folder / repository | Every deploy |

Test a restore once before launch.

## 9. Cut-over from WordPress (checklist)

Do this in a quiet hour. Keep the WordPress site untouched until the new site has been live for at least two weeks.

**Before (days ahead)**
- [ ] Fix the TLS certificate on the current host (see the box at the top).
- [ ] Lower the DNS TTL of the `idealers.net` A/AAAA (and `www`) records to 300 seconds at least 24 hours before the switch. Note the current values (needed for rollback).
- [ ] Note what else uses the domain: MX/mail records, `autoconfig.idealers.net`, `help.idealers.net` (knowledge base), `idealers.app` is a different domain. Change **only** the web records for `idealers.net` and `www`.
- [ ] Take a full WordPress backup (files + database) and save the old `/sitemap_index.xml` and a crawl/list of all URLs (for redirect spot checks).
- [ ] Deploy the new site on the new server; test it with a hosts-file entry (`<new IP> idealers.net`) or on a staging hostname with `SITE_NOINDEX=true`.
- [ ] Issue the TLS certificate for `idealers.net` and `www.idealers.net` on the new server (Let's Encrypt with DNS challenge, or HTTP challenge right after the switch).
- [ ] On staging run: `php scripts/parity/check.php --base=https://staging-host`, `php scripts/qa/seo-smoke.php --base=...`, `php scripts/qa/links.php --base=...` (all must pass), and check the three forms and six Stripe buttons by hand.
- [ ] In the admin: set the GA4 measurement ID (and GTM if used), Search Console verification if the HTML-tag method is used, and check Site settings.
- [ ] Set `SITE_NOINDEX=false` on production and run `php artisan optimize`.

**Switch**
- [ ] Change the A/AAAA records of `idealers.net` and `www.idealers.net` to the new server.
- [ ] Once DNS answers with the new IP (`dig +short idealers.net`), check: `https://idealers.net/` loads with a valid certificate, `http://` and `www.` redirect to `https://idealers.net/`, `/about` redirects to `/about/`, `/wp-admin/` returns 410.

**Rollback plan** (if a blocking problem appears and cannot be fixed within the agreed window, for example forms or payments broken)
1. Point the A/AAAA records back to the old values noted above (TTL is 300 s, so most visitors return within minutes).
2. Leave the new server running for diagnosis; do not change the WordPress site meanwhile.
3. Note: admin edits made on the new site during the window are not in WordPress; list them before switching back.
4. Fix, retest on staging, and repeat the switch.

## 10. Post-launch checks

Same day:
- [ ] `php scripts/qa/seo-smoke.php --base=https://idealers.net` and `php scripts/qa/links.php --base=https://idealers.net --external` pass (HSTS must now show PASS).
- [ ] `php scripts/parity/check.php --base=https://idealers.net` passes.
- [ ] Redirect spot checks: `/about` -> `/about/`, `/sitemap_index.xml` and `/page-sitemap.xml` -> `/sitemap.xml`, `/feed/` -> 410, a few old URLs from the saved WordPress sitemap all return 200 or a 301 to the right page.
- [ ] Contact, Request a Demo and Talk to Sales pages: the idealers.app form loads inside the page and can be submitted (check with the owner that the lead arrived).
- [ ] Pricing and Design Studio: each of the six plan buttons opens the right Stripe checkout.
- [ ] Analytics: accept cookies on the live site, then open Google Analytics > Reports > Realtime and confirm your visit appears (and in Tag Assistant that consent changes from denied to granted). Decline cookies in a private window and confirm nothing is sent.
- [ ] `storage/logs/laravel-*.log` has no errors after browsing every page.

Within a few days:
- [ ] Google Search Console: Sitemaps > remove `sitemap_index.xml` and `page-sitemap.xml`, submit `https://idealers.net/sitemap.xml`; URL Inspection > request indexing for the home page and the product pages; watch Pages / Core Web Vitals for new errors over the next weeks.
- [ ] Bing Webmaster Tools: submit the same sitemap.
- [ ] Check that Google's cached title and description for the home page are unchanged after recrawl.
- [ ] Remove the old WordPress hosting only after two weeks without issues, and keep its backup.
