xonecas.io
8356
Wx

www-xonecas-io / files

www-xonecas-io / README.md

3.8 KB
1# xonecas.io
2
3My projects and their git history, as a site. `site serve` reads the git repos and renders each page when it is asked
4for, with htmx swapping pages in place of full reloads. It also serves `git clone` of every project at `/<name>.git`.
5
6```
7 git push over SSH ─► login-shell ─► repos/xonecas.io/<name>.git ─┐
8                                                                  ├─► site index ─► data/projects.json ─► site serve
9 sources.txt ─► site import ─► repos/<host>/<owner>/<repo>.git ───┤
10                                                  overrides.txt ──┘
11```
12
13## Start
14
15```sh
16make site          # builds bin/site
17make import        # mirrors every repo in sources.txt into repos/
18make index         # reads repos/ into data/projects.json
19make serve         # serves the site on http://vm:8080
20```
21
22Run everything from this folder. `bin/site help` lists the commands, and `bin/site <command> -h` lists a command's flags.
23
24## Push a repo from anywhere
25
26You push to your own account on the server, with its password or any key. The first push creates the repo, the way
27`gh repo create` would, and each push updates the site.
28
29**Once, on the server,** in the site folder, as the user that owns it:
30
31```sh
32make login-shell
33```
34
35It makes `login-shell.sh` your login shell. Pushes and clones of `<name>.git`, and `remote`, go to `bin/site`. Everything
36else (your logins, ssh commands, scp, sftp) still gets your own shell, and a repo that already exists in your home is
37pushed to as before. To undo it: `sudo chsh -s /bin/bash $USER`.
38
39**Then, from any machine:**
40
41```sh
42git remote add origin sean@xonecas.io:my-thing.git    # or: git remote set-url origin ...
43git push -u origin main
44ssh sean@xonecas.io remote list                        # remote new|add|rm work the same way
45```
46
47If it says `does not appear to be a git repository`, `make login-shell` hasn't run on the server for that user.
48
49## Manage repos
50
51| To | Run |
52| --- | --- |
53| Start a repo the site hosts | `git push` to `sean@xonecas.io:my-thing.git`, or `remote new my-thing` first, which prints that URL |
54| Show a repo you already have | `bin/site remote add ~/code/other-thing` (a path) or `bin/site remote add https://host/owner/repo.git` |
55| Stop showing a repo | `bin/site remote rm <path or url>` (a hosted repo's data is kept) |
56| List the repos | `bin/site remote list` |
57| Fetch every added repo again | `make import` |
58| Update the site | `make index` (the running site reads the new data on its next request) |
59
60A push to a hosted repo runs `site index` by itself; its log is `repos/xonecas.io/<name>.git/build.log`.
61After `remote add` or `rm`, run `make index`.
62
63`repos/` is git-ignored. On the VM it is lost when the VM is recreated, so host repos on the machine that serves the site.
64
65## Fix how a project shows
66
67Edit `overrides.txt`, one rule per line, then `make index`:
68
69```
70merge <remote URL> <remote URL>   make two remotes one project
71rename <name> <new name>          rename a project
72hide <name>                       hide a project
73show <name>                       list a fork or an empty repo, which are hidden by default
74tag <name> +frontend -backend     add or drop tags
75```
76
77## Layout
78
79| Path | Holds |
80| --- | --- |
81| `cmd/site` | the `site` command: import, remote, shell, index, serve, help |
82| `internal/store` | the repo store: `sources.txt`, mirrors, hosted repos, the hosts' metadata |
83| `internal/project` | groups repos into projects, and their tags, description and overrides |
84| `internal/server` | serves the site: picks each page, reads git once per data file, and serves clones |
85| `internal/site` | renders each page, and the htmx parts in its templates |
86| `internal/repo` | runs git against a bare repo |
87| `tickets/` | the Rats board |
88
89`make test` runs the tests.