chore: updated docs
545e8e2e
2 file(s) · +93 −0
| 1 | + | # Kepler |
|
| 2 | + | # |
|
| 3 | + |  |
|
| 4 | + | ||
| 5 | + | Kepler is a read-only web view for on-disk git repositories. It's drop-in compatible with softserve's `<data>/repos` layout. Point `KEPLER_REPO_ROOT` at your directory and browse your repos in the browser, no database or auth required. |
|
| 6 | + | ||
| 7 | + | - Single Go binary with embedded assets |
|
| 8 | + | - Repo index with description + last-commit time |
|
| 9 | + | - README rendering (goldmark) |
|
| 10 | + | - Tree / blob browsing at any ref (branch, tag, SHA) |
|
| 11 | + | - Raw file download |
|
| 12 | + | - Commit log with pagination and single-commit diff view |
|
| 13 | + | - Branches + tags page |
|
| 14 | + | - Archive download: `.tar.gz`, `.zip` |
|
| 15 | + | - Atom feed per repo |
|
| 16 | + | - Dark themed UI with Commit Mono font |
|
| 17 | + | ||
| 18 | + | ## Configure |
|
| 19 | + | ||
| 20 | + | ### Environment Variables |
|
| 21 | + | ||
| 22 | + | | Variable | Description | Default | |
|
| 23 | + | |---|---|---| |
|
| 24 | + | | `HOST` | Bind address (use `0.0.0.0` in Docker) | `127.0.0.1` | |
|
| 25 | + | | `PORT` | Listen port | `4747` | |
|
| 26 | + | | `KEPLER_REPO_ROOT` | Directory of bare repos (`*.git/`) or normal repos | `./repos` | |
|
| 27 | + | | `KEPLER_SITE_NAME` | Site name shown in the header and feed | `kepler` | |
|
| 28 | + | | `KEPLER_BASE_URL` | Public base URL for Open Graph / social meta tags | `http://localhost:4747` | |
|
| 29 | + | | `KEPLER_CLONE_BASE_URL` | HTTPS entry in the repo-home Clone menu (URL = `<base>/<repo>.git`). Point at the host that actually serves git (e.g. softserve), not kepler | _(empty)_ | |
|
| 30 | + | | `KEPLER_CLONE_SSH_HOST` | SSH (scp-style) entry in the Clone menu (URL = `<user@host>:<repo>.git`, e.g. `git@git.example.com`). Include the user | _(empty)_ | |
|
| 31 | + | ||
| 32 | + | The repo-home **Clone** dropdown shows whichever of `KEPLER_CLONE_BASE_URL` and `KEPLER_CLONE_SSH_HOST` are set; if both are empty the button is hidden. Kepler only serves a web view — point the clone URLs at the host that actually serves git over HTTPS/SSH. |
|
| 33 | + | ||
| 34 | + | ## Deploy |
|
| 35 | + | ||
| 36 | + | ### Docker |
|
| 37 | + | ||
| 38 | + | ```bash |
|
| 39 | + | cd apps/kepler |
|
| 40 | + | cp .env.example .env |
|
| 41 | + | # Edit .env, set KEPLER_REPO_ROOT to your repos directory |
|
| 42 | + | docker compose up -d |
|
| 43 | + | ``` |
|
| 44 | + | ||
| 45 | + | The compose file mounts `KEPLER_REPO_ROOT` into the container read-only at `/data/repos`, so Kepler can never modify your repositories. |
|
| 46 | + | ||
| 47 | + | ### Binary |
|
| 48 | + | ||
| 49 | + | Build from source: |
|
| 50 | + | ||
| 51 | + | ```bash |
|
| 52 | + | cd apps/kepler && go build . |
|
| 53 | + | ``` |
|
| 54 | + | ||
| 55 | + | The resulting binary is self-contained with all assets embedded. Copy it to your server with a configured `.env` file and run it directly. |
|
| 56 | + | ||
| 57 | + | ## Use |
|
| 58 | + | ||
| 59 | + | Point `KEPLER_REPO_ROOT` at a directory of git repos and start the server: |
|
| 60 | + | ||
| 61 | + | ```bash |
|
| 62 | + | KEPLER_REPO_ROOT=~/.local/share/soft-serve/repos go run . |
|
| 63 | + | ``` |
|
| 64 | + | ||
| 65 | + | Then open `http://127.0.0.1:4747` |
|
| 66 | + | ||
| 67 | + | ### Repo discovery |
|
| 68 | + | ||
| 69 | + | Each entry of `KEPLER_REPO_ROOT` is treated as a candidate: |
|
| 70 | + | ||
| 71 | + | - `<name>.git/` → bare repo; display name = stripped basename. |
|
| 72 | + | - `<name>/.git/` → non-bare repo; display name = dirname. |
|
| 73 | + | ||
| 74 | + | A `description` file in the repo directory shows on the index and repo home (softserve writes this; the default placeholder is filtered out). |
|
| 75 | + | ||
| 76 | + | ### Routes |
|
| 77 | + | ||
| 78 | + | | Path | Purpose | |
|
| 79 | + | |---|---| |
|
| 80 | + | | `/` | Repo index | |
|
| 81 | + | | `/{repo}` | Repo home (README + latest commit) | |
|
| 82 | + | | `/{repo}/refs` | Branches and tags | |
|
| 83 | + | | `/{repo}/log/{ref}` | Commit log (paginated) | |
|
| 84 | + | | `/{repo}/commit/{sha}` | Single-commit diff | |
|
| 85 | + | | `/{repo}/tree/{ref}/{path...}` | Directory tree at a ref | |
|
| 86 | + | | `/{repo}/blob/{ref}/{path...}` | Syntax-highlighted file view | |
|
| 87 | + | | `/{repo}/raw/{ref}/{path...}` | Raw file download | |
|
| 88 | + | | `/{repo}/archive/{name}` | Archive download (`.tar.gz`, `.zip`) | |
|
| 89 | + | | `/{repo}/atom.xml` | Per-repo Atom feed | |
| 65 | 65 | link: '/apps/jotts', |
|
| 66 | 66 | }, |
|
| 67 | 67 | { |
|
| 68 | + | text: 'Kepler', |
|
| 69 | + | link: '/apps/kepler', |
|
| 70 | + | }, |
|
| 71 | + | { |
|
| 68 | 72 | text: 'Library', |
|
| 69 | 73 | link: '/apps/library', |
|
| 70 | 74 | }, |