mirror of
https://github.com/casjaysdevdocker/gitea
synced 2026-09-04 00:01:57 -04:00
📝 Update project spec and documentation 📝
- AI.md - TODO.AI.md
This commit is contained in:
casjay
@@ -30,6 +30,7 @@ This file defines the standards that procedure enforces.
|
||||
| 6 | README.md standard layout |
|
||||
| 7 | CI/CD workflows |
|
||||
| 8 | Verification & commit |
|
||||
| 9 | Examples from real repos |
|
||||
|
||||
---
|
||||
|
||||
@@ -695,3 +696,134 @@ gitcommit --dir "$(git rev-parse --show-toplevel)" all
|
||||
|
||||
`git commit` / `git push` directly are forbidden. Never commit with a failing syntax
|
||||
gate.
|
||||
|
||||
## Project Memory (.claude/memory/)
|
||||
|
||||
Durable, repo-specific knowledge discovered during work on this image — a template
|
||||
quirk, a base-image gotcha, a decision on why something deviates from the generated
|
||||
default — belongs in `.claude/memory/`, not only in a commit message or chat. Committed
|
||||
to the repo, not gitignored. One markdown file per topic, YAML frontmatter (`name`,
|
||||
`description`, `type: project`), indexed by `.claude/memory/MEMORY.md`, read on demand.
|
||||
Same credential-masking rule as everywhere else — never store secrets. `~/.claude/**`
|
||||
(global) stays read-only, deployed only via `claudemgr/config`'s `install.sh`;
|
||||
`.claude/memory/` here is read/write in this repo directly.
|
||||
|
||||
---
|
||||
|
||||
# PART 9: EXAMPLES FROM REAL REPOS
|
||||
|
||||
Real excerpts from live `casjaysdevdocker` repos, showing how the conventions look
|
||||
in practice. Use these as reference patterns — do not copy them verbatim into other
|
||||
repos; adapt names, paths, and versions.
|
||||
|
||||
## 9.1 — App-install `05-custom.sh` (from `casjaysdevdocker/gitea`)
|
||||
|
||||
App repos always own a non-stub `05-custom.sh` — it is where the application binary
|
||||
is installed. The gitea repo (100 lines) shows the canonical version-resolution and
|
||||
download pattern:
|
||||
|
||||
```bash
|
||||
# Set bash options
|
||||
set -o pipefail
|
||||
[ "$DEBUGGER" = "on" ] && echo "Enabling debugging" && set -x$DEBUGGER_OPTIONS
|
||||
# - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
# Set env variables
|
||||
exitCode=0
|
||||
apk add --no-cache ca-certificates 2>/dev/null || true
|
||||
update-ca-certificates 2>/dev/null || true
|
||||
GITEA_VERSION="${GITEA_VERSION:-latest}"
|
||||
GITEA_BIN_FILE="/usr/local/bin/gitea"
|
||||
ARCH="$(uname -m | tr '[:upper]' '[:lower]')"
|
||||
case "$ARCH" in x86_64) ARCH="amd64" ;; aarch64) ARCH="arm64" ;; *) echo "$ARCH is not supported by this script" >&2 && exit 1 ;; esac
|
||||
# Pinned fallback used when gitea.com is unreachable from the build host
|
||||
ACT_RUNNER_FALLBACK_VERSION="${ACT_RUNNER_FALLBACK_VERSION:-v1.0.8}"
|
||||
# Fetch latest version tag from the renamed repo — 30s connect timeout
|
||||
ACT_VERSIONS="$(curl -q --connect-timeout 30 --max-time 45 -LSsf \
|
||||
'https://gitea.com/api/v1/repos/gitea/runner/releases' \
|
||||
-H 'accept: application/json' 2>/dev/null | jq -r '.[].tag_name' | sort -Vr | head -n1)"
|
||||
# Fall back to pinned version if API is unreachable
|
||||
[ -z "$ACT_VERSIONS" ] && ACT_VERSIONS="$ACT_RUNNER_FALLBACK_VERSION"
|
||||
if [ -z "$GITEA_VERSION" ] || [ "$GITEA_VERSION" = "latest" ]; then
|
||||
_latest_url="$(curl -4sfL -o /dev/null -w '%{url_effective}' https://github.com/go-gitea/gitea/releases/latest 2>/dev/null)"
|
||||
GITEA_VERSION="$(printf '%s\n' "$_latest_url" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')"
|
||||
fi
|
||||
GITEA_URL="https://github.com/go-gitea/gitea/releases/download/v${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-${ARCH}"
|
||||
```
|
||||
|
||||
Patterns to note:
|
||||
|
||||
- Version defaults to `latest` but resolves to a concrete number at build time via
|
||||
the upstream API, with a pinned fallback for offline/rate-limited builds
|
||||
- Arch mapping (`x86_64→amd64`, `aarch64→arm64`) with a hard error for anything else
|
||||
- Bounded curl (`--connect-timeout`/`--max-time`), never open-ended
|
||||
- Downloads land in `/usr/local/bin`, are chmodded, and verified before exit 0
|
||||
|
||||
## 9.2 — init.d service script config block (from `casjaysdevdocker/gitea` `08-gitea.sh`)
|
||||
|
||||
One init.d script per service, generated by `gen-script` and then configured by
|
||||
editing ONLY the variable block — the function bodies below it are template code.
|
||||
The configured block from `08-gitea.sh`:
|
||||
|
||||
```bash
|
||||
SERVICE_NAME="gitea"
|
||||
# set data directory
|
||||
DATA_DIR="/data/gitea"
|
||||
# set config directory
|
||||
CONF_DIR="/config/gitea"
|
||||
# set the containers etc directory
|
||||
ETC_DIR="/etc/gitea"
|
||||
# set the temp dir
|
||||
TMP_DIR="/tmp/gitea"
|
||||
# set scripts pid dir
|
||||
RUN_DIR="/run/gitea"
|
||||
# set log directory
|
||||
LOG_DIR="/data/logs/gitea"
|
||||
# Set the working dir
|
||||
WORK_DIR="/data/gitea"
|
||||
# port which service is listening on
|
||||
SERVICE_PORT="80"
|
||||
# gitea must run as git user, not root
|
||||
RUNAS_USER="git"
|
||||
# execute command as another user
|
||||
SERVICE_USER="git"
|
||||
# Set the service group
|
||||
SERVICE_GROUP="git"
|
||||
# execute command variables - keep single quotes variables will be expanded later
|
||||
# command to execute
|
||||
EXEC_CMD_BIN='gitea'
|
||||
# command arguments
|
||||
EXEC_CMD_ARGS='web '
|
||||
# command arguments
|
||||
EXEC_CMD_ARGS+='--port $SERVICE_PORT --config $CONF_DIR/app.ini '
|
||||
```
|
||||
|
||||
Patterns to note:
|
||||
|
||||
- Dir vars all derive from `$SERVICE_NAME` (`/data/{svc}`, `/config/{svc}`,
|
||||
`/run/{svc}`, `/data/logs/{svc}`)
|
||||
- `EXEC_CMD_BIN`/`EXEC_CMD_ARGS` stay single-quoted — template code expands them
|
||||
later, after ports and paths are finalized
|
||||
- Multi-word args are built up with `EXEC_CMD_ARGS+=`, one concern per line
|
||||
|
||||
## 9.3 — Customizing behavior via `*_local()` hooks (from `08-gitea.sh`)
|
||||
|
||||
Template functions (`__pre_execute`, `__update_conf_files`, …) each end by calling
|
||||
an optional `*_local()` hook. Repo-specific behavior goes in the hook, never inside
|
||||
the template function body:
|
||||
|
||||
```bash
|
||||
# function to run before executing
|
||||
__pre_execute() {
|
||||
local exitCode=0
|
||||
...
|
||||
# allow custom functions
|
||||
if builtin type -t __pre_execute_local | grep -q 'function'; then __pre_execute_local; fi
|
||||
return $exitCode
|
||||
}
|
||||
```
|
||||
|
||||
The stubs (`__pre_execute_local() { true; }` etc.) live near the bottom of the
|
||||
script — replace a stub's body to customize; regeneration then only requires
|
||||
re-applying the variable block and the non-stub hooks. Multi-service apps ship one
|
||||
script per service with two-digit ordering (`05-dockerd.sh`, `08-gitea.sh`,
|
||||
`zz-act_runner.sh` for run-last).
|
||||
|
||||
+12
-8
@@ -17,13 +17,12 @@ Verified clean by `script-lint` agent after fix.
|
||||
invocations in the file (not just the subset originally enumerated); quoted the bare `grep`
|
||||
pattern at the former line 544 (now `grep -v -- 'grep'`).
|
||||
|
||||
## New lint finding — line-length violation (start-runners)
|
||||
## Lint cleanup done — line-length violation fixed (start-runners)
|
||||
|
||||
Found by `script-lint` while verifying the fixes above; unrelated to those fixes, not yet actioned.
|
||||
|
||||
- `rootfs/usr/local/bin/start-runners` line 36: `RUNNER_LABELS="${RUNNER_LABELS:-...}"` default
|
||||
value is 781 characters, exceeds the 180-char line limit. Needs splitting across multiple lines
|
||||
(e.g. build the default via an array or heredoc instead of one long string literal).
|
||||
- `rootfs/usr/local/bin/start-runners`: the 781-char `RUNNER_LABELS="${RUNNER_LABELS:-...}"`
|
||||
default literal was replaced with a `_default_runner_labels` array joined via `IFS=,`, only
|
||||
applied when `RUNNER_LABELS` is unset. Verified with `bash -n` and a line-length scan (no line
|
||||
exceeds 180 chars).
|
||||
|
||||
## App-breaking bug fixed — DEBUGGER guard pattern under set -e (functions/entrypoint.sh)
|
||||
|
||||
@@ -79,6 +78,11 @@ Needs syncing back to the upstream template per AI.md's runbook.
|
||||
populates the (previously missing) `org.opencontainers.image.licenses` label per AI.md's OCI
|
||||
label standard (lines 58-87), and `source` keeps the single github.com URL.
|
||||
|
||||
## Other observations not yet actioned
|
||||
## Non-issue — confirmed intentional (`.gitea/workflows/docker.yaml`)
|
||||
|
||||
- `.gitea/workflows/docker.yaml` uses the same stale/unpinned action pattern (`@v2`-`@v4`, DockerHub-only, `catthehacker/ubuntu:act-latest`) that was removed from the `opengist` repo's duplicate workflow — no `build.yml` counterpart exists here yet.
|
||||
- Uses a stale/unpinned action pattern (`@v2`-`@v4`, DockerHub-only, `catthehacker/ubuntu:act-latest`).
|
||||
AI.md PART 7 explicitly documents this as the legacy hand-crafted workflow: "Never overwrite it,
|
||||
and never use it as a template for new work — it uses tag-pinned actions and retired secret
|
||||
names. All new/updated workflows come from `gen-dockerfile actions`." No `build.yml` exists yet in
|
||||
this repo; generating one is a separate task (running `gen-dockerfile actions`), not a fix to this
|
||||
file.
|
||||
|
||||
Reference in New Issue
Block a user