# Putting Eric's 3D Services live

This is the whole checklist, in order. Nothing here needs a developer once it is set up.

## 1. What the host needs

- PHP 8.1 or newer with these extensions: `pdo_mysql`, `curl`, `mbstring`, `zip`, `openssl`, `gd`, `fileinfo`.
- MariaDB 10.5+ or MySQL 8.
- HTTPS (a free certificate from the host or Let's Encrypt).
- Cron (to run one command every minute).

## 2. Where things go

```
/home/you/e3d/                 <- the whole "app" folder, OUTSIDE the public web folder
    config/config.local.php    <- you create this (secrets)
    storage/                   <- uploads, backups, logs (must be writable, never public)
/home/you/public_html/         <- the "site" folder (the pages people see)
    api/                       <- contents of app/public (index.php, .htaccess) so /api/... reaches PHP
```

If your host only allows one web folder, put `app/public/index.php` at `public_html/api/index.php`, edit its first `require` line to point at the real `app` folder, and keep everything else of `app` above the web folder.

The web server must send every `/api/*` request to `api/index.php`. On Apache the included `.htaccess` does it. On nginx:

```nginx
location /api/ { try_files /api/index.php$is_args$args; }   # then pass .php to php-fpm as usual
location ~ ^/(storage|config|src|database|bin|tests)/ { deny all; }
```

## 3. First-time setup

1. Create an empty database and a database user with full rights on it.
2. `cp config/config.local.sample.php config/config.local.php`, then fill in the database login and `app_url`.
3. `php bin/make-key.php` and paste the result into `app_key`. **Keep a copy in a password manager.** Without it, saved keys and 2-step secrets cannot be read, even from a backup.
4. `php bin/install.php` (creates the tables). It does not add test accounts unless you pass `--dev`, which is refused when `env` is `prod`.
5. Create the owner login: `php bin/create-owner.php you@example.com "Your Name"`. At first sign-in you set up your authenticator app (2-step sign-in is required for all staff).
6. In `config/config.local.php` make sure there is **no** `dev_skip_2fa` line and `env` is `prod`.
7. Cron, every minute: `* * * * * php /home/you/e3d/bin/cron.php >> /home/you/e3d/storage/logs/cron.log 2>&1`

## 4. Switch on email

1. Admin, Settings, Email: fill in From address, and the SMTP server your email provider gives you (host, port 587, TLS, user name, password).
2. Keep `'mail' => ['driver' => 'smtp', ...]` in `config.local.php`.
3. Admin, Backups and system, **Send me a test email**. It shows the provider's exact error if something is wrong.
4. At your DNS host add the SPF and DKIM records your provider lists (and a DMARC record). Without them mail lands in spam.

Newsletters and marketing emails carry a one-click unsubscribe header and link automatically. Each customer's choices (order, quote, support, marketing emails) are respected; receipts, refunds, quote prices and security mail are always sent.

## 5. Alerts to your phone (optional)

Create a Telegram bot with @BotFather, put its token and your chat id in Settings, Alerts, then use **Send a test Telegram alert** on the system page. Quiet hours hold alerts until morning.

## 6. Payments

Settings, Payments (or Integrations): paste the PayPal client id and secret, and switch from Sandbox to Live only after one successful sandbox order. The webhook address to give PayPal is `https://YOUR-DOMAIN/api/webhooks/paypal`.

## 7. Social sign-in (optional)

Settings, Integrations: add each provider's client id and secret. In each provider's console set the redirect address to `https://YOUR-DOMAIN/api/auth/social/PROVIDER/callback`. Leave a provider empty and its button stays hidden.

## 8. Web server headers

Send these from the web server for the whole site (the API already sends its own):

```
Strict-Transport-Security: max-age=31536000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
```

## 9. Backups

- Automatic: every night at 2:00 shop time, kept 14 days, in `storage/backups` (not public).
- By hand: admin, Backups and system, **Back up now**, or `php bin/backup.php`.
- **Copy them off the server.** A backup on the same machine does not survive losing the machine. Download one each week from the system page, or point your host's own backup tool at `storage/backups`.
- Restore (replaces everything): `php bin/restore.php storage/backups/e3d-YYYYMMDD-HHMMSS.zip --yes`. Test this once on a spare database before you need it.

## 10. Launch-day checks

- [ ] Open the site over https; the padlock shows and `http://` redirects to it.
- [ ] Sign in as the owner with 2-step; confirm no one can sign in without it.
- [ ] Place a sandbox PayPal order, then a Live one for a small amount, and refund it from the order page.
- [ ] Test email arrives and is not in spam; click the unsubscribe link in a newsletter test.
- [ ] Backups and system shows the job running ("Running", last run under a minute ago) and a backup exists.
- [ ] `https://YOUR-DOMAIN/robots.txt` and `/sitemap.xml` load and use the real domain.
- [ ] Delete any test orders, test customers and the dev accounts (`owner@example.test`, `customer@example.test`).

## Addresses without ".html"

The public site uses clean addresses (`/products`, `/account/orders`, `/quote`). The pages themselves are still `.html` files; the web server maps one to the other.

- **Apache:** the `.htaccess` that sits next to `index.html` in the `site` folder does it. Make sure `mod_rewrite` is on and the folder allows `AllowOverride All` (or at least `FileInfo` and `Indexes`). Old `.html` links, bookmarks and emails redirect to the clean address (301) and keep their query string.
- **nginx:** add this inside `server { ... }`:

```nginx
# old .html addresses -> clean ones
if ($request_uri ~ ^(/.*?)(?:/index)?\.html(\?.*)?$) { return 301 $1$2; }
location / { try_files $uri $uri.html $uri/ =404; }
error_page 404 /404.html;
```

(`/index.html` should redirect to `/`; the rule above turns `/account/index.html` into `/account`, and `try_files $uri/` then serves the folder index.)
- There is no ".php" in any public address: the API lives at `/api/...` and the front controller `index.php` is never shown.
- After deploying, `sitemap.xml` and `robots.txt` already use the clean form.

## Before you open the shop: run the launch check

On the live server, from the app folder:

    php bin/preflight.php

It only reads. It lists everything that still needs doing (dev mode left on, the "skip 2FA" shortcut, sample accounts and orders,
no real mail server or PayPal keys, no backup, the scheduled job not running, and more) and ends with how many things are left.
Run it again after each fix; when it says "All clear" you are ready.

## Keys you can enter in the admin

Admin, Integrations now takes PayPal (client id, secret, mode, webhook id), outgoing email (SMTP), Etsy (shop, API keystring, shared secret) and the Google, Facebook and Apple sign-in keys. Keys are stored encrypted and never shown again. PayPal and email entered there take the place of the lines in config.local.php; with nothing entered the settings file is used. "Sync now" on PayPal checks that PayPal accepts the keys. Sign-in keys are saved but the buttons stay off until the provider flow is switched on. Telegram and Discord have one Send/Off choice per alert.


## 8. Search engines and page headers

- In `config/config.local.php` set `'static_dir'` to the real path of the public folder (the one holding `index.html`). The server reads `product.html` and `project.html` from there to add each product's title, description, picture and star ratings for Google and link previews, and the nightly job rewrites `sitemap.xml` there.
- Keep `site/.htaccess` in the public folder. It sends product and project addresses through `/api/seo/page/...`, adds the security headers and page policy, and sets caching. It needs `mod_rewrite`, `mod_headers`, `mod_deflate` and `mod_expires` (all normal on shared hosting). On nginx, copy the same headers into your server block and send `/product?p=` and `/project?id=` to `/api/seo/page/product` and `/api/seo/page/project`.
- If you ever turn on Google Analytics or change what the pages load from other sites, update the policy in two places together: `site/.htaccess` and `Seo::CSP` in `src/Core/Seo.php`.
- After going live, add the site in Google Search Console and Bing Webmaster Tools and submit `https://YOUR-DOMAIN/sitemap.xml`.
- When `env` is `prod` and PayPal is not connected, checkout shows "Online payment is not available" instead of the test payment window.
