docs: real README + deploy notes for FlexHub branding
README documents what FlexHub is (rebrand of git.s8n.ru), the git.s8n.ru/flexhub.s8n.ru hostname split, and the layout of the Forgejo custom/ tree. docs/DEPLOY.md covers updating the homepage template, theme CSS, app.ini, image assets, and the Traefik file provider router on nullstone. Repo previously contained only a one-line README + the home.tmpl override; this fills in the operator-facing docs so flexhub becomes the canonical project page (referenced as a mirror by ARRFLIX).
This commit is contained in:
parent
2556871bfd
commit
db1d54ada1
2 changed files with 283 additions and 2 deletions
93
README.md
93
README.md
|
|
@ -1,3 +1,92 @@
|
|||
# flexhub
|
||||
# FlexHub
|
||||
|
||||
FlexHub — where I flex my projects, code, and stuff
|
||||
> Where I flex my projects, code, and stuff. A place to flex.
|
||||
|
||||
FlexHub is the brand wrapped around the operator's self-hosted Forgejo
|
||||
instance. Same git host, same backing store — different paint job.
|
||||
|
||||
- **Canonical URL:** <https://git.s8n.ru/> (admin / push / clone)
|
||||
- **FlexHub-branded entry:** <https://flexhub.s8n.ru/> (public showcase)
|
||||
|
||||
Both hostnames hit the same Forgejo container on `nullstone`. Repos,
|
||||
PATs, SSH keys, issues — all identical. Login sessions are independent
|
||||
(separate cookies per hostname).
|
||||
|
||||
This repository holds the customisations that turn vanilla Forgejo into
|
||||
FlexHub: the homepage template, the theme CSS, the logo set, and the
|
||||
deploy notes that wire it all together.
|
||||
|
||||
---
|
||||
|
||||
## What's in this repo
|
||||
|
||||
| Path | Purpose |
|
||||
| ------------------------------------------------ | ------------------------------------------------------------------------ |
|
||||
| `templates/home.tmpl` | FlexHub homepage. Wordmark + tagline + 4-card "agent grid" feature list. |
|
||||
| `public/assets/css/theme-flexhub.css` *(planned)* | The orange/black/white theme. `DEFAULT_THEME = flexhub` in `app.ini`. |
|
||||
| `public/assets/img/` *(planned)* | Logo + wordmark + favicons (`logo.svg`, `flexhub-wordmark.png`, etc). |
|
||||
| `docs/DEPLOY.md` | How to roll a change out to the live `nullstone` Forgejo container. |
|
||||
| `LICENSE` | MIT. |
|
||||
|
||||
The repo is currently template-only; assets get checked in as the
|
||||
operator pulls them out of the live Forgejo `custom/` tree. The
|
||||
authoritative copies live on `nullstone` until then.
|
||||
|
||||
---
|
||||
|
||||
## How it's wired up
|
||||
|
||||
Forgejo loads any file under `custom/` to override the equivalent
|
||||
built-in. On `nullstone` that directory is bind-mounted from the host:
|
||||
|
||||
```
|
||||
/home/docker/forgejo/data/gitea/ → /var/lib/gitea/ (in-container)
|
||||
└─ custom/
|
||||
├─ conf/app.ini
|
||||
├─ templates/home.tmpl ← from this repo
|
||||
├─ public/assets/css/... ← from this repo
|
||||
└─ public/assets/img/... ← from this repo
|
||||
```
|
||||
|
||||
The Forgejo container itself is described by the compose file at
|
||||
`/opt/docker/forgejo/docker-compose.yml`. Container data + customisations
|
||||
live under `/home/docker/forgejo/` because the root volume on nullstone
|
||||
is small.
|
||||
|
||||
Key settings in `app.ini` that drive the rebrand:
|
||||
|
||||
```ini
|
||||
APP_NAME = FlexHub
|
||||
DEFAULT_THEME = flexhub
|
||||
THEMES = forgejo-auto,forgejo-light,forgejo-dark,flexhub,veilor
|
||||
```
|
||||
|
||||
The two hostnames are split at the Traefik layer, not Forgejo:
|
||||
|
||||
- `git.s8n.ru` — docker-provider router, gated by `no-guest@file` ACL.
|
||||
- `flexhub.s8n.ru` — file-provider router, **public**, no `no-guest`,
|
||||
rate-limited login. Service `flexhub-svc` points at `http://forgejo:3000`
|
||||
directly (avoids the file→docker provider race; see DEPLOY.md).
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Don't. This is the operator's personal git host — accounts are
|
||||
invite-only, registration is disabled. If you've found a real bug in
|
||||
Forgejo itself, file it upstream at
|
||||
<https://codeberg.org/forgejo/forgejo>. If you've found a typo on the
|
||||
homepage, open an issue here and the operator will get to it.
|
||||
|
||||
Public read access is intentional: browse repos, clone what's MIT or
|
||||
AGPL, mirror what you like. That's the "flex" part.
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
- **Deploy + update workflow:** [`docs/DEPLOY.md`](docs/DEPLOY.md)
|
||||
- **Initial Forgejo bring-up runbook (operator-internal):**
|
||||
`_github/infra/forgejo/DEPLOY.md` in the `ai-lab` repo.
|
||||
- **ARRFLIX project** references `flexhub.s8n.ru` as a mirror — that's
|
||||
this instance.
|
||||
|
|
|
|||
192
docs/DEPLOY.md
Normal file
192
docs/DEPLOY.md
Normal file
|
|
@ -0,0 +1,192 @@
|
|||
# Deploying FlexHub customisations
|
||||
|
||||
These notes cover **updating an already-running** FlexHub. If you're
|
||||
standing up Forgejo from scratch on a new host, follow the
|
||||
operator-internal runbook at `_github/infra/forgejo/DEPLOY.md` in the
|
||||
`ai-lab` repo first, then come back here for the rebrand layer.
|
||||
|
||||
All paths below are on `nullstone` (the host running the Forgejo
|
||||
container). The container is named `forgejo`. Host UID 1000 owns the
|
||||
data tree.
|
||||
|
||||
---
|
||||
|
||||
## Layout on nullstone
|
||||
|
||||
```
|
||||
/opt/docker/forgejo/
|
||||
└── docker-compose.yml ← image tag, env, traefik labels
|
||||
|
||||
/home/docker/forgejo/
|
||||
├── data/
|
||||
│ └── gitea/
|
||||
│ └── custom/ ← Forgejo "override" tree
|
||||
│ ├── conf/app.ini ← APP_NAME, DEFAULT_THEME, THEMES
|
||||
│ ├── templates/
|
||||
│ │ └── home.tmpl ← homepage (mirror of this repo)
|
||||
│ └── public/assets/
|
||||
│ ├── css/theme-flexhub.css
|
||||
│ └── img/ ← logos + favicons
|
||||
└── config/ ← Forgejo-managed; don't hand-edit
|
||||
```
|
||||
|
||||
`custom/` is the only path you ever edit by hand. Everything in this
|
||||
repo maps 1:1 into that tree.
|
||||
|
||||
---
|
||||
|
||||
## Update the homepage template
|
||||
|
||||
Edit `templates/home.tmpl` here, then on `nullstone`:
|
||||
|
||||
```bash
|
||||
ssh nullstone bash <<'EOF'
|
||||
sudo cp /tmp/home.tmpl /home/docker/forgejo/data/gitea/custom/templates/home.tmpl
|
||||
sudo chown 1000:1000 /home/docker/forgejo/data/gitea/custom/templates/home.tmpl
|
||||
EOF
|
||||
```
|
||||
|
||||
Forgejo hot-reloads templates — no container restart needed. Hit
|
||||
<https://flexhub.s8n.ru/> and hard-refresh (Ctrl+Shift+R) to confirm.
|
||||
|
||||
If the page renders blank, check the Forgejo log for a template parse
|
||||
error:
|
||||
|
||||
```bash
|
||||
ssh nullstone 'docker logs --tail 50 forgejo 2>&1 | grep -i template'
|
||||
```
|
||||
|
||||
The wrapping `{{template "base/head" .}}` and `{{template "base/footer" .}}`
|
||||
calls are mandatory — drop them and you get a half-page.
|
||||
|
||||
---
|
||||
|
||||
## Update the theme CSS
|
||||
|
||||
Edit `public/assets/css/theme-flexhub.css`, copy to nullstone:
|
||||
|
||||
```bash
|
||||
ssh nullstone bash <<'EOF'
|
||||
sudo cp /tmp/theme-flexhub.css \
|
||||
/home/docker/forgejo/data/gitea/custom/public/assets/css/theme-flexhub.css
|
||||
sudo chown 1000:1000 \
|
||||
/home/docker/forgejo/data/gitea/custom/public/assets/css/theme-flexhub.css
|
||||
EOF
|
||||
```
|
||||
|
||||
CSS is served static — no reload needed. The theme is selected
|
||||
per-user via `DEFAULT_THEME = flexhub` in `app.ini` (see next section)
|
||||
and is overridable in user settings.
|
||||
|
||||
The brand palette is **orange `#FF9000` / black `#000` / white `#FFF`**.
|
||||
Don't drift.
|
||||
|
||||
---
|
||||
|
||||
## Bump APP_NAME or theme list
|
||||
|
||||
`app.ini` lives at `/home/docker/forgejo/data/gitea/custom/conf/app.ini`
|
||||
on nullstone (Forgejo merges custom values over its built-in defaults).
|
||||
The relevant keys:
|
||||
|
||||
```ini
|
||||
APP_NAME = FlexHub
|
||||
DEFAULT_THEME = flexhub
|
||||
THEMES = forgejo-auto,forgejo-light,forgejo-dark,flexhub,veilor
|
||||
```
|
||||
|
||||
After editing `app.ini` you **must restart the container** — env-style
|
||||
INI is read at boot only:
|
||||
|
||||
```bash
|
||||
ssh nullstone 'cd /opt/docker/forgejo && docker compose restart forgejo'
|
||||
```
|
||||
|
||||
Watch the log come back clean:
|
||||
|
||||
```bash
|
||||
ssh nullstone 'docker logs -f --tail 30 forgejo'
|
||||
```
|
||||
|
||||
You're good when you see `Listen: http://0.0.0.0:3000`. The web UI
|
||||
should now show the new title bar / theme list.
|
||||
|
||||
---
|
||||
|
||||
## Add a new template override
|
||||
|
||||
Forgejo template hierarchy:
|
||||
<https://forgejo.org/docs/latest/admin/customization/#changing-the-look-of-forgejo>.
|
||||
The general flow:
|
||||
|
||||
1. Find the upstream template in the Forgejo source tree
|
||||
(`templates/...`).
|
||||
2. Copy its full content into `custom/templates/<same path>.tmpl` on
|
||||
nullstone, owned `1000:1000`.
|
||||
3. Edit your override.
|
||||
4. Mirror the file into this repo under `templates/<same path>.tmpl`
|
||||
so the repo stays the source of truth.
|
||||
|
||||
Hot-reload applies — no container restart.
|
||||
|
||||
If the override stops rendering after a Forgejo version bump, diff
|
||||
your override against the new upstream template — base layout slots
|
||||
sometimes get renamed across major versions.
|
||||
|
||||
---
|
||||
|
||||
## Add a new image asset
|
||||
|
||||
```bash
|
||||
scp my-asset.png nullstone:/tmp/
|
||||
ssh nullstone bash <<'EOF'
|
||||
sudo cp /tmp/my-asset.png \
|
||||
/home/docker/forgejo/data/gitea/custom/public/assets/img/my-asset.png
|
||||
sudo chown 1000:1000 \
|
||||
/home/docker/forgejo/data/gitea/custom/public/assets/img/my-asset.png
|
||||
EOF
|
||||
```
|
||||
|
||||
Reachable at `https://flexhub.s8n.ru/assets/img/my-asset.png`. No
|
||||
container restart.
|
||||
|
||||
When replacing favicons specifically, also clear the browser cache —
|
||||
favicons are aggressively cached.
|
||||
|
||||
---
|
||||
|
||||
## Traefik routing for `flexhub.s8n.ru`
|
||||
|
||||
The FlexHub-branded hostname is wired in via a **file-provider** router
|
||||
(`/opt/docker/traefik/config/dynamic.yml` on nullstone), not via the
|
||||
docker-provider labels on the Forgejo compose file. This is intentional:
|
||||
|
||||
- `git.s8n.ru` — docker-provider router, `no-guest@file` middleware.
|
||||
- `flexhub.s8n.ru` — file-provider router, public, rate-limit only.
|
||||
|
||||
The file-provider router defines its **own** service
|
||||
(`flexhub-svc`) pointing at `http://forgejo:3000` directly, rather than
|
||||
referencing `forgejo@docker`. This works around a startup race where
|
||||
file-provider routers can resolve before docker-provider services are
|
||||
populated, leaving the router permanently broken with
|
||||
`the service "forgejo@docker" does not exist`.
|
||||
|
||||
If you change the Forgejo container name or move it off the `proxy`
|
||||
network, update `flexhub-svc.loadBalancer.servers[0].url` in
|
||||
`dynamic.yml` to match.
|
||||
|
||||
---
|
||||
|
||||
## Rollback
|
||||
|
||||
The customisations are pure overlay files. To revert FlexHub branding:
|
||||
|
||||
```bash
|
||||
ssh nullstone bash <<'EOF'
|
||||
sudo mv /home/docker/forgejo/data/gitea/custom /home/docker/forgejo/data/gitea/custom.disabled
|
||||
EOF
|
||||
ssh nullstone 'cd /opt/docker/forgejo && docker compose restart forgejo'
|
||||
```
|
||||
|
||||
Forgejo falls back to vanilla theme + homepage. Nothing in the data
|
||||
store changes. Restore by renaming `custom.disabled` back to `custom`.
|
||||
Loading…
Reference in a new issue