ac/ac-docs
1
0
Fork 0
mirror of git://f0xx.org/ac/ac-docs synced 2026-07-29 04:39:12 +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

103
docs/FRESH_ENV_CLONE.md
View File

@@ -1,90 +1,77 @@
# Fresh developer machine — clone guide
Use this on a **clean laptop** (no legacy `android_cast` monolith checkout).
Canonical layout: org **`ac`** on `git://f0xx.org/ac/*`, branch **`next`**.
Use on a **clean laptop**. Canonical org: **`ac`** on `git://f0xx.org/ac/*`, branch **`next`**.
## One command (recommended)
From any empty directory (requires `git` and reachability to `git://f0xx.org`):
## Standard layout (`~/repos/ac`)
```bash
# Bootstrap: shallow clone ac-scripts only, then run the full workspace clone
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
```
mkdir -p ~/repos/ac && cd ~/repos/ac
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 update --init --recursive
# Sanity: expect 32 submodule directories + ac-workspace root
find . -maxdepth 1 -type d -name 'ac-*' | wc -l
echo 'source "$(git rev-parse --show-toplevel)/ac-be-public-assets/ac-bash.env"' >> ~/.bashrc
source ~/.bashrc
```
# Spot-check remotes (each submodule should be git://f0xx.org/ac/<name>)
git submodule foreach --quiet 'echo $name $(git rev-parse --short HEAD) $(git remote get-url origin)'
You now have every `ac-*` submodule under one directory. Docs: `ac-docs/` (start with [DEVELOPER_SETUP.md](../DEVELOPER_SETUP.md)).
## 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
| Path under workspace | Role |
|----------------------|------|
| Path | Role |
|------|------|
| `ac-mobile-android/` | Android app |
| `ac-deploy/` | Lab cluster (`sim/cluster0/`), compose scripts |
| `ac-docs/` | Documentation (this file) |
| `ac-scripts/` | `fresh-clone-dev-env.sh`, CI helpers |
| `ac-platform-*` | DB, PHP, web, edge nginx snippets |
| `ac-ms-*`, `ac-be-*` | Backend microservices and consoles |
| `ac-deploy/` | Lab cluster (`sim/cluster0/`) |
| `ac-docs/` | Documentation |
| `ac-be-public-assets/` | Shared `ac-bash.env` (non-secret) |
| `ac-platform-*`, `ac-ms-*`, `ac-be-*` | Backend stack |
**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
| Task | Where |
|------|--------|
| 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` |
| 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 |
|-------------|------------|--------------|
| Production (current) | `https://apps.f0xx.org/app/androidcast_project/issues/` | prod BE Gitea |
| Lab cluster (cast01) | `https://acl0.f0xx.org/...` (after FE `ac-fe.conf`) | `.../git/ac/` |
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.
| Environment | Issues API |
|-------------|------------|
| Production | `https://apps.f0xx.org/app/androidcast_project/issues/` |
| Lab cluster | `https://acl0.f0xx.org/...` (after FE `ac-fe.conf`) |
## Troubleshooting
| Symptom | Fix |
|---------|-----|
| `git://f0xx.org` unreachable | VPN/LAN to git host; try from cluster or PO network |
| Submodule empty dir | `git submodule update --init --recursive` in workspace root |
| `git://f0xx.org` unreachable | VPN/LAN to git host |
| Empty submodule dir | `git submodule update --init --recursive` |
| 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 |