ac/ac-docs
1
0
Fork 0
mirror of git://f0xx.org/ac/ac-docs synced 2026-07-29 05:18:46 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: bestcastr Gmail, ~/repos/ac clone, Cursor handoff, help_request update

Browse Source 
Replace foxxspambox0 with bestcastr@gmail.com; document ac-be-public-assets
and secondary-laptop Cursor archive workflow.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Anton Afanasyeu
2026-06-23 18:24:11 +02:00
parent 4164a2216e
commit 0582aea607
6 changed files with 157 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
20260607-2FA-email-mobile-auth-flow.md
View File

@@ -51,7 +51,7 @@ _Date: 2026-06-07 — FR §9 (email) + FR §10 (registration, 2FA, mobile) — *
- [§9 — Email addresses & agent config](#9-email-addresses-agent-config) - [§9 — Email addresses & agent config](#9-email-addresses-agent-config)
- [§9.1 Prerequisites](#91-prerequisites) - [§9.1 Prerequisites](#91-prerequisites)
- [§9.2 Register addresses (free — DNS, not “buy mailboxes”)](#92-register-addresses-free-dns-not-buy-mailboxes) - [§9.2 Register addresses (free — DNS, not “buy mailboxes”)](#92-register-addresses-free-dns-not-buy-mailboxes)
- [§9.3 Forward / duplicate to Gmail (info@ → foxxspambox0@gmail.com)](#93-forward-duplicate-to-gmail-info-foxxspambox0gmailcom) - [§9.3 Forward / duplicate to Gmail (info@ → bestcastr@gmail.com)](#93-forward-duplicate-to-gmail-info-foxxspambox0gmailcom)
- [§9.4 Recommended prod layout for this project](#94-recommended-prod-layout-for-this-project) - [§9.4 Recommended prod layout for this project](#94-recommended-prod-layout-for-this-project)
- [§9.5 Outbound mail from BE (verification emails)](#95-outbound-mail-from-be-verification-emails) - [§9.5 Outbound mail from BE (verification emails)](#95-outbound-mail-from-be-verification-emails)
- [§10 — Registration, 2FA, mobile auth](#10-registration-2fa-mobile-auth) - [§10 — Registration, 2FA, mobile auth](#10-registration-2fa-mobile-auth)
@@ -128,7 +128,7 @@ You do **not** need to buy Google Workspace or Microsoft 365 mailboxes. You **do
| 3 | **Inbound path** | MX records → free forwarder **or** self-hosted Postfix alias on FE/BE. | | 3 | **Inbound path** | MX records → free forwarder **or** self-hosted Postfix alias on FE/BE. |
| 4 | **Outbound path (BE)** | SMTP relay for verification/reset mail (see §9.5) — can be Gmail SMTP, SendGrid free tier, or local Postfix with SPF alignment. | | 4 | **Outbound path (BE)** | SMTP relay for verification/reset mail (see §9.5) — can be Gmail SMTP, SendGrid free tier, or local Postfix with SPF alignment. |
| 5 | **TLS on web** | Already have `https://apps.f0xx.org` — verification links use same vhost. | | 5 | **TLS on web** | Already have `https://apps.f0xx.org` — verification links use same vhost. |
| 6 | **Gmail destination** | e.g. `foxxspambox0@gmail.com` — receives forwarded + BCC copies. | | 6 | **Gmail destination** | e.g. `bestcastr@gmail.com` — receives forwarded + BCC copies. |
**Deliverability minimum (avoid spam folder):** **Deliverability minimum (avoid spam folder):**
@@ -147,7 +147,7 @@ Start with `p=none`; tighten after monitoring.
#### Option A — **Cloudflare Email Routing** (recommended if DNS is on Cloudflare) #### Option A — **Cloudflare Email Routing** (recommended if DNS is on Cloudflare)
1. Cloudflare dashboard → **Email** → **Email Routing** → enable for `apps.f0xx.org`. 1. Cloudflare dashboard → **Email** → **Email Routing** → enable for `apps.f0xx.org`.
2. Add **destination address** `foxxspambox0@gmail.com` (verify Gmail link once). 2. Add **destination address** `bestcastr@gmail.com` (verify Gmail link once).
3. Create **Custom addresses**: 3. Create **Custom addresses**:
- `info@apps.f0xx.org` → forward to Gmail - `info@apps.f0xx.org` → forward to Gmail
- `admin@apps.f0xx.org` → forward to Gmail - `admin@apps.f0xx.org` → forward to Gmail
@@ -161,7 +161,7 @@ Start with `p=none`; tighten after monitoring.
1. Sign up at [improvmx.com](https://improvmx.com) (free tier: limited aliases). 1. Sign up at [improvmx.com](https://improvmx.com) (free tier: limited aliases).
2. Add domain `apps.f0xx.org` → set MX to ImprovMX hosts (they show exact records). 2. Add domain `apps.f0xx.org` → set MX to ImprovMX hosts (they show exact records).
3. Create aliases `info`, `admin`, `root` → `foxxspambox0@gmail.com`. 3. Create aliases `info`, `admin`, `root` → `bestcastr@gmail.com`.
4. Add SPF include for ImprovMX. 4. Add SPF include for ImprovMX.
#### Option C — **Self-hosted alias** (Gentoo FE or Alpine BE) #### Option C — **Self-hosted alias** (Gentoo FE or Alpine BE)
@@ -170,16 +170,16 @@ If you already run Postfix on FE:
```text ```text
/etc/postfix/virtual: /etc/postfix/virtual:
info@apps.f0xx.org foxxspambox0@gmail.com info@apps.f0xx.org bestcastr@gmail.com
admin@apps.f0xx.org foxxspambox0@gmail.com admin@apps.f0xx.org bestcastr@gmail.com
root@apps.f0xx.org foxxspambox0@gmail.com root@apps.f0xx.org bestcastr@gmail.com
``` ```
Then `postmap /etc/postfix/virtual && systemctl reload postfix`. Requires **MX** pointing to FE public IP and port **25** reachable (often blocked on residential; OK on HVM with firewall rule). Then `postmap /etc/postfix/virtual && systemctl reload postfix`. Requires **MX** pointing to FE public IP and port **25** reachable (often blocked on residential; OK on HVM with firewall rule).
**Do first:** pick **A or B** unless you explicitly want to operate SMTP on FE. **Do first:** pick **A or B** unless you explicitly want to operate SMTP on FE.
### §9.3 Forward / duplicate to Gmail (info@ → foxxspambox0@gmail.com) ### §9.3 Forward / duplicate to Gmail (info@ → bestcastr@gmail.com)
| Method | Inbox copy | Send-as From | IMAP on apps domain | | Method | Inbox copy | Send-as From | IMAP on apps domain |
|--------|------------|--------------|---------------------| |--------|------------|--------------|---------------------|
@@ -201,9 +201,9 @@ No IMAP/POP3 server on `apps.f0xx.org` is required for this FR.
```text ```text
Inbound (public): Inbound (public):
info@apps.f0xx.org ──forward──► foxxspambox0@gmail.com info@apps.f0xx.org ──forward──► bestcastr@gmail.com
admin@apps.f0xx.org ──forward──► foxxspambox0@gmail.com admin@apps.f0xx.org ──forward──► bestcastr@gmail.com
root@apps.f0xx.org ──forward──► foxxspambox0@gmail.com (same inbox or +tag) root@apps.f0xx.org ──forward──► bestcastr@gmail.com (same inbox or +tag)
Outbound (BE PHP): Outbound (BE PHP):
From: Android Cast Issues <noreply@apps.f0xx.org> From: Android Cast Issues <noreply@apps.f0xx.org>
@@ -438,7 +438,7 @@ Hub landing contact form (`landing-pages.inc.php`) should eventually use **`info
|---|----------|------------------| |---|----------|------------------|
| Q1 | Require WebAuthn for alpha or TOTP-only? | **TOTP required**; WebAuthn optional P4 | | Q1 | Require WebAuthn for alpha or TOTP-only? | **TOTP required**; WebAuthn optional P4 |
| Q2 | Allow registration on prod immediately or invite-only? | **Open register** with captcha; `viewer` role | | Q2 | Allow registration on prod immediately or invite-only? | **Open register** with captcha; `viewer` role |
| Q3 | Single Gmail inbox for all aliases? | Yes for now (`foxxspambox0@gmail.com`) | | Q3 | Single Gmail inbox for all aliases? | Yes for now (`bestcastr@gmail.com`) |
| Q4 | Separate `noreply@` for outbound? | Yes — no forward needed; SPF only | | Q4 | Separate `noreply@` for outbound? | Yes — no forward needed; SPF only |
--- ---

9
DEVELOPER_SETUP.md
View File

@@ -1,8 +1,13 @@
# Developer setup — org `ac` # Developer setup — org `ac`
**Clean machine?** Start with [docs/FRESH_ENV_CLONE.md](docs/FRESH_ENV_CLONE.md) and run `ac-scripts/fresh-clone-dev-env.sh`. **Clean machine?** Start with [docs/FRESH_ENV_CLONE.md](docs/FRESH_ENV_CLONE.md) (`~/repos/ac`).
Canonical entry point: **`ac-workspace`** (submodule manifest). ```bash
mkdir -p ~/repos/ac && cd ~/repos/ac
git clone --branch next --single-branch git://f0xx.org/ac/ac-workspace .
git submodule update --init --recursive
echo 'source "$(git rev-parse --show-toplevel)/ac-be-public-assets/ac-bash.env"' >> ~/.bashrc
```
```bash ```bash
git clone git://f0xx.org/ac/ac-workspace git clone git://f0xx.org/ac/ac-workspace

4
README.md
View File

@@ -11,5 +11,7 @@ AndroidCast documentation (extracted from monolith `docs/`).
| Doc | Purpose | | Doc | Purpose |
|-----|---------| |-----|---------|
| [DEVELOPER_SETUP.md](DEVELOPER_SETUP.md) | Repo map, lab paths | | [DEVELOPER_SETUP.md](DEVELOPER_SETUP.md) | Repo map, lab paths |
| [docs/FRESH_ENV_CLONE.md](docs/FRESH_ENV_CLONE.md) | Clean laptop — clone all `ac/*` repos | | [docs/FRESH_ENV_CLONE.md](docs/FRESH_ENV_CLONE.md) | Clean laptop — `~/repos/ac` clone workflow |
| [docs/CURSOR_SECONDARY_LAPTOP.md](docs/CURSOR_SECONDARY_LAPTOP.md) | Agent history handoff between laptops |
| [docs/HELP_REQUEST_20260623.md](docs/HELP_REQUEST_20260623.md) | Updated dev checklist (email, clone) |
| [docs/SECRETS_AND_RECOVERY.md](docs/SECRETS_AND_RECOVERY.md) | Passwords, tokens, VPN/RSSH recovery | | [docs/SECRETS_AND_RECOVERY.md](docs/SECRETS_AND_RECOVERY.md) | Passwords, tokens, VPN/RSSH recovery |

54
docs/CURSOR_SECONDARY_LAPTOP.md Normal file
View File

@@ -0,0 +1,54 @@
# Cursor IDE — second laptop / agent handoff
Cursor does not ship a single “export entire IDE” button. Use this checklist to move **code + rules + agent chat history** to another machine.
## 1. Code (required)
On the **new** laptop, follow [FRESH_ENV_CLONE.md](FRESH_ENV_CLONE.md) (`~/repos/ac`).
## 2. Workspace rules (recommended)
Copy from the old machine:
| Source | Destination on new laptop |
|--------|---------------------------|
| `~/repos/ac/.cursor/rules/` (if present) | same under workspace |
| `~/repos/ac/AGENTS.md` | workspace root |
Or re-clone — rules live in `ac-docs` / monolith exports when committed.
## 3. Agent conversation history
Cursor stores transcripts per project, e.g.:
`~/.cursor/projects/<project-slug>/agent-transcripts/*.jsonl`
**Handoff archive** (run on the **old** laptop from repo root):
```bash
cd ~/repos/ac
tar czvf ~/ac-cursor-handoff-$(date +%Y%m%d).tar.gz \
.cursor/rules 2>/dev/null \
AGENTS.md 2>/dev/null \
-C "$HOME/.cursor/projects" \
$(ls -1d "$HOME/.cursor/projects"/*androidcast* 2>/dev/null | xargs -I{} basename {})
```
Copy the `.tar.gz` to the new laptop and extract:
```bash
mkdir -p ~/.cursor/projects
tar xzvf ac-cursor-handoff-YYYYMMDD.tar.gz -C ~
```
Open **`~/repos/ac`** in Cursor on the new machine — past chats appear under that project when the slug matches.
## 4. What is *not* portable
- Local Cursor login / API keys (re-sign-in)
- Uncommitted work (commit or stash before switch)
- Cluster secrets (`secrets.lab.env` on NFS — not in git)
## 5. Scripted helper
`ac-scripts/export-cursor-handoff.sh` — builds the tarball paths above.

103
docs/FRESH_ENV_CLONE.md
View File

@@ -1,90 +1,77 @@
# Fresh developer machine — clone guide # Fresh developer machine — clone guide
Use this on a **clean laptop** (no legacy `android_cast` monolith checkout). Use on a **clean laptop**. Canonical org: **`ac`** on `git://f0xx.org/ac/*`, branch **`next`**.
Canonical layout: org **`ac`** on `git://f0xx.org/ac/*`, branch **`next`**.
## One command (recommended) ## Standard layout (`~/repos/ac`)
From any empty directory (requires `git` and reachability to `git://f0xx.org`):
```bash ```bash
# Bootstrap: shallow clone ac-scripts only, then run the full workspace clone mkdir -p ~/repos/ac && cd ~/repos/ac
git clone --branch next --single-branch --depth 1 \
git://f0xx.org/ac/ac-scripts /tmp/ac-scripts-bootstrap
sh /tmp/ac-scripts-bootstrap/fresh-clone-dev-env.sh
```
Default target: `~/src/androidcast-ac/` (override with `-d /path`). git clone --branch next --single-branch git://f0xx.org/ac/ac-workspace .
The script:
1. Clones **`ac-workspace`** (submodule manifest).
2. Runs `git submodule update --init --recursive` on **`next`**.
3. Verifies every submodule path exists and prints a SHA summary.
4. Exits non-zero if any submodule is missing or unreachable.
## Manual steps (review / teach)
```bash
export AC_GIT_BASE=git://f0xx.org/ac
export AC_BRANCH=next
export TARGET=~/src/androidcast-ac
mkdir -p "$(dirname "$TARGET")"
git clone --branch "$AC_BRANCH" --single-branch \
"${AC_GIT_BASE}/ac-workspace" "$TARGET"
cd "$TARGET"
git submodule sync --recursive git submodule sync --recursive
git submodule update --init --recursive git submodule update --init --recursive
# Sanity: expect 32 submodule directories + ac-workspace root echo 'source "$(git rev-parse --show-toplevel)/ac-be-public-assets/ac-bash.env"' >> ~/.bashrc
find . -maxdepth 1 -type d -name 'ac-*' | wc -l source ~/.bashrc
```
# Spot-check remotes (each submodule should be git://f0xx.org/ac/<name>) You now have every `ac-*` submodule under one directory. Docs: `ac-docs/` (start with [DEVELOPER_SETUP.md](../DEVELOPER_SETUP.md)).
git submodule foreach --quiet 'echo $name $(git rev-parse --short HEAD) $(git remote get-url origin)'
## Stay up to date
From `~/repos/ac`:
```bash
git pull --rebase origin next
git submodule sync --recursive
git submodule update --init --recursive
```
Or, after sourcing `ac-bash.env`: **`ac-pull`**
When child repos change on the server, the workspace root commit updates submodule SHAs — always pull **root first**, then submodule update.
## One-command bootstrap (alternative)
```bash
git clone --branch next --single-branch --depth 1 \
git://f0xx.org/ac/ac-scripts /tmp/ac-scripts-bootstrap
sh /tmp/ac-scripts-bootstrap/fresh-clone-dev-env.sh -d ~/repos/ac
``` ```
## What you get ## What you get
| Path under workspace | Role | | Path | Role |
|----------------------|------| |------|------|
| `ac-mobile-android/` | Android app | | `ac-mobile-android/` | Android app |
| `ac-deploy/` | Lab cluster (`sim/cluster0/`), compose scripts | | `ac-deploy/` | Lab cluster (`sim/cluster0/`) |
| `ac-docs/` | Documentation (this file) | | `ac-docs/` | Documentation |
| `ac-scripts/` | `fresh-clone-dev-env.sh`, CI helpers | | `ac-be-public-assets/` | Shared `ac-bash.env` (non-secret) |
| `ac-platform-*` | DB, PHP, web, edge nginx snippets | | `ac-platform-*`, `ac-ms-*`, `ac-be-*` | Backend stack |
| `ac-ms-*`, `ac-be-*` | Backend microservices and consoles |
**Do not** clone legacy `git://f0xx.org/android_cast` for new work — it is frozen read-only. **Do not** clone legacy `git://f0xx.org/android_cast` for new work.
## After clone ## After clone
| Task | Where | | Task | Where |
|------|--------| |------|--------|
| Repo map, lab URLs | [DEVELOPER_SETUP.md](../DEVELOPER_SETUP.md) | | Repo map, lab URLs | [DEVELOPER_SETUP.md](../DEVELOPER_SETUP.md) |
| Passwords / tokens / VPN recovery | [SECRETS_AND_RECOVERY.md](SECRETS_AND_RECOVERY.md) | | Secrets / recovery | [SECRETS_AND_RECOVERY.md](SECRETS_AND_RECOVERY.md) |
| Cursor + second laptop | [CURSOR_SECONDARY_LAPTOP.md](CURSOR_SECONDARY_LAPTOP.md) |
| Android build | `cd ac-mobile-android && ./gradlew :app:assembleDebug` | | Android build | `cd ac-mobile-android && ./gradlew :app:assembleDebug` |
| Unit tests | `./gradlew :app:testDebugUnitTest` |
| Lab cluster (optional) | `ac-deploy/sim/cluster0/DEPLOY.md` |
## Lab vs production URLs ## Lab vs production
| Environment | Issues API | Gitea browse | | Environment | Issues API |
|-------------|------------|--------------| |-------------|------------|
| Production (current) | `https://apps.f0xx.org/app/androidcast_project/issues/` | prod BE Gitea | | Production | `https://apps.f0xx.org/app/androidcast_project/issues/` |
| Lab cluster (cast01) | `https://acl0.f0xx.org/...` (after FE `ac-fe.conf`) | `.../git/ac/` | | Lab cluster | `https://acl0.f0xx.org/...` (after FE `ac-fe.conf`) |
Mobile defaults target **production** until you point a debug build at lab (`BackendEndpoints` / settings).
## Version note (post-migration)
After migration completes, **app and backend minor versions will bump**. Older mobile builds were not publicly released; lab/prod may **reject** clients below the new minimum. Rebuild from `ac-mobile-android` on `next` after pulling.
## Troubleshooting ## Troubleshooting
| Symptom | Fix | | Symptom | Fix |
|---------|-----| |---------|-----|
| `git://f0xx.org` unreachable | VPN/LAN to git host; try from cluster or PO network | | `git://f0xx.org` unreachable | VPN/LAN to git host |
| Submodule empty dir | `git submodule update --init --recursive` in workspace root | | Empty submodule dir | `git submodule update --init --recursive` |
| Wrong branch | `git checkout next && git submodule foreach git checkout next` | | Wrong branch | `git checkout next && git submodule foreach git checkout next` |
| SSH instead of git | Not required for read-only clone; push uses `git://` on FE |

36
docs/HELP_REQUEST_20260623.md Normal file
View File

@@ -0,0 +1,36 @@
# Developer help request — updated 2026-06-23
Supersedes `tmp/20260608_help_request.md` for **email inbox** and **clone workflow**.
Original PDF still valid for DNS/MX items not listed here.
## Done / updated by agent
| Item | Status |
|------|--------|
| Gmail destination | **`bestcastr@gmail.com`** (replaces foxxspambox0@gmail.com) |
| alpine-be msmtp | `bestcastr@gmail.com` + app password in `/etc/androidcast/msmtp.secret` |
| Lab cluster mail | cast01: `deploy-mailrelay.sh` (msmtp), PHP `sendmail` transport |
| Dev clone path | `~/repos/ac` ← `git clone git://f0xx.org/ac/ac-workspace .` |
| `ac-be-public-assets` | `ac-bash.env` for shared non-secret env |
## Your verification (after agent test send)
1. Check **`bestcastr@gmail.com`** inbox for:
- msmtp CLI smoke from cast01 (`Lab mail relay` or similar subject from verify script)
- Optional: registration mail after you test `/issues/register`
2. Reply: **“mail received”** or paste failure (Gmail spam, delay, etc.)
## Still on you (unchanged from 20260608)
| Task | Notes |
|------|--------|
| **2.1 DNS** | MX/SPF/DKIM/DMARC — apex `f0xx.org` if `apps.f0xx.org` is CNAME |
| **ImprovMX** | Activate aliases `info@` / `admin@` / `root@` → **bestcastr@gmail.com** (hoster.by partial) |
| **FE acl0** | Install `ac-fe.conf` on monstro — see `ac-platform-edge/fe/INSTALL.md` |
| **Inbound** | Confirm forwarded mail to bestcastr@gmail.com after ImprovMX live |
## References
- [20260607-2FA-email-mobile-auth-flow.md](../20260607-2FA-email-mobile-auth-flow.md)
- [FRESH_ENV_CLONE.md](FRESH_ENV_CLONE.md)
- [SECRETS_AND_RECOVERY.md](SECRETS_AND_RECOVERY.md)