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.