LINUXBOSS API — Flask + MySQL backend for Wasmer Edge

Real database + real authentication for the LINUXBOSS website. Once this is deployed and wired up, admin dashboard edits go live for everyone, instantly.

Browser ──> Static site (Wasmer Edge, this repo root)
              │  fetch https://<your-api>.wasmer.app/api/...
              ▼
         API app (Wasmer Edge, backend/ folder, Flask)
              │  MySQL over TCP (credentials in Wasmer Secrets)
              ▼
         MySQL database (Wasmer)

🔒 Security rule: database credentials live ONLY in Wasmer Secrets (production) or backend/.env (local dev, never committed). Never paste passwords into chat, code, or screenshots.

---

1. Prerequisites

• Python 3.11+ installed (python --version)
• Wasmer CLI installed + wasmer login done
• Your Wasmer MySQL credentials (host, port, database, user, password)

2. Configure

cd backend
cp .env.example .env
# Now edit .env and fill in your DB_* values + generated secrets:

Generate the two secrets (any machine with Python):

python -c "import secrets; print(secrets.token_hex(32))"
# run twice: once for JWT_SECRET, once for SETUP_TOKEN

3. Vendor dependencies (no virtualenv needed)

pip install --target=deps -r requirements.txt

This creates backend/deps/ with Flask, PyMySQL and PyJWT (pure-Python wheels, safe for the Wasmer runner). Works identically on Windows, Mac and Linux.

4. Set your Wasmer username

Edit backend/wasmer.toml and replace YOUR-WASMER-USERNAME with your own Wasmer username (find it in your wasmer.io profile URL).

5. Create the tables (run once)

Point any MySQL client at your Wasmer database and run schema.sql:

mysql -h <DB_HOST> -u <DB_USER> -p <DB_NAME> < schema.sql

(Or paste the file into MySQL Workbench / DBeaver / your host's SQL console.)

6. Deploy the API

cd backend
wasmer deploy
# Note the URL you get, e.g. https://linuxboss-api-<you>.wasmer.app

7. Attach secrets + redeploy

cd backend
wasmer app secrets create --from-file=.env
wasmer deploy

(Alternative: App dashboard → Settings → Secrets → add each variable, then redeploy. Secrets only take effect after a redeploy.)

Quick check: open https://<your-api>/api/health (should say ok) and https://<your-api>/api/ready (should say "db": "up").

If /api/ready says unreachable: double-check the DB_* secrets, and if your database doesn't support SSL, set DB_SSL=false as a secret and redeploy.

8. One-time setup (creates admin + seeds content)

Replace the URL, token, email and password:

curl -X POST https://<your-api>/api/setup \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_SETUP_TOKEN","email":"you@example.com","password":"a-long-password-min-10-chars"}'

• Uses the SETUP_TOKEN from your secrets. Works exactly once (refuses when a user already exists).
• Seeds profile/projects/collaborations/settings from src/seed.json (generated from the site's data/*.json).
• No curl? Any REST client (Postman, Insomnia, Thunder Client) works too.

9. Wire the frontend to the API

1. Open js/config.js and paste your API URL: apiUrl: "https://<your-api>.wasmer.app" (no trailing slash).
2. Rebuild + redeploy the frontend:

   ./build-public.sh   # or build-public.bat on Windows
   wasmer deploy
   

3. Open https://<your-site>/admin.html and log in with your real email + password. The topbar shows ● ONLINE — every save now goes live globally.

---

API reference (quick)

Method	Path	Auth	Purpose
GET	/api/health, /api/ready	–	status checks
GET	/api/public	–	whole site bundle (what the homepage reads)
POST	/api/setup	setup token	one-time init + seed
POST	/api/auth/login	–	→ {token} (JWT, 12h)
GET	/api/auth/me	✓	validate session
POST	/api/auth/change-password	✓	change password
GET/PUT	/api/profile, /api/settings	PUT ✓	site content docs
GET/POST	/api/projects, /api/collaborations	POST ✓	create
PUT/DELETE	/api/projects/<id>, /api/collaborations/<id>	✓	edit/delete

Auth header: Authorization: Bearer <token>.

Local development

cd backend
pip install -r requirements.txt   # or reuse deps/ via PYTHONPATH
python src/main.py                # serves http://127.0.0.1:5080 (needs .env)

Troubleshooting

• /api/ready → database unreachable: wrong DB_* secret, or SSL mismatch (try DB_SSL=false + redeploy), or DB host not reachable from Edge.
• Login fails after setup: the admin email is whatever you passed to /api/setup (check for typos; emails are lowercased).
• Setup says "Already initialized": admin exists — just log in. To start over, empty the users table in SQL and call setup again.
• CORS errors in browser console: set CORS_ORIGINS secret to your site URL (or *) and redeploy.
• Deploy complains about package name: you forgot step 4 (username in wasmer.toml).