Initial docs: creating repos, importing codebases, going public

4 files changed, 208 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a4a4b60
--- /dev/null
+++ b/README.md
@@ -0,0 +1,23 @@
+# gwaihir git server — how-to guide
+
+This little self-hosted git server runs on `gwaihir` (gitolite over SSH for
+push/pull, cgit over HTTPS for read-only browsing at
+[git.veltar.systems](https://git.veltar.systems)). This repo is the docs.
+
+- [Creating a new repo from scratch](creating-a-repo-from-scratch.md)
+- [Importing an existing codebase](importing-an-existing-codebase.md)
+- [Making a repo public (cgit)](making-a-repo-public.md)
+
+## The short version
+
+You (any user in the `@creators` group) can create a repo yourself, no
+admin involvement needed, under your own namespace:
+
+```
+git@git.veltar.systems:personal/<your-username>/<reponame>
+```
+
+The repo doesn't exist until your first push — that push *is* the
+creation step. It's private (SSH-only) by default. See the linked docs
+for the details, and [making-a-repo-public.md](making-a-repo-public.md)
+if you also want it browsable on the web.
diff --git a/creating-a-repo-from-scratch.md b/creating-a-repo-from-scratch.md
new file mode 100644
index 0000000..1e0b369
--- /dev/null
+++ b/creating-a-repo-from-scratch.md
@@ -0,0 +1,61 @@
+# Creating a new repo from scratch
+
+This works for anyone in the `@creators` gitolite group (currently
+`bryan` and `red`). You don't need to ask an admin to declare the repo
+first — pushing to a name under your own `personal/<you>/...` namespace
+creates it automatically.
+
+## 1. Pick a name
+
+```
+personal/<your-username>/<reponame>
+```
+
+e.g. `personal/bryan/my-project`. You can only create repos under your
+own username segment — gitolite checks the pushing user's identity
+against that path component, so `red` can create `personal/red/...` but
+gets denied on `personal/bryan/...`.
+
+## 2. Clone the (not-yet-existing) repo
+
+```bash
+git clone git@git.veltar.systems:personal/bryan/my-project
+```
+
+Git will warn "you appear to have cloned an empty repository" — that's
+expected, it doesn't exist on the server yet.
+
+## 3. Add something and push
+
+```bash
+cd my-project
+echo "# my-project" > README.md
+git add README.md
+git commit -m "Initial commit"
+git push -u origin master   # or main, whichever branch you're on
+```
+
+That push is what actually creates the bare repo on gwaihir. From here
+on it's a completely normal git remote.
+
+## 4. (Optional) give someone else access
+
+You own this repo (`RW+`) and can grant others access yourself, without
+an admin editing any config:
+
+```bash
+ssh git@git.veltar.systems perms personal/bryan/my-project + RW someone
+```
+
+Use `RW+` instead of `RW` if they should also be able to force-push /
+rewrite history. To revoke, replace `+` with `-`:
+
+```bash
+ssh git@git.veltar.systems perms personal/bryan/my-project - RW someone
+```
+
+## What this doesn't do
+
+Creating the repo does **not** make it visible on the web UI
+(`git.veltar.systems`) — it's SSH-only until an admin explicitly adds it
+to cgit's config. See [making-a-repo-public.md](making-a-repo-public.md).
diff --git a/importing-an-existing-codebase.md b/importing-an-existing-codebase.md
new file mode 100644
index 0000000..84dd215
--- /dev/null
+++ b/importing-an-existing-codebase.md
@@ -0,0 +1,56 @@
+# Importing an existing codebase
+
+Same repo-creation mechanism as
+[creating-a-repo-from-scratch.md](creating-a-repo-from-scratch.md) — the
+only difference is you already have code and possibly existing git
+history, so you're pointing an existing local repo at gwaihir instead of
+starting from an empty clone.
+
+## Case A: your project is already a git repo
+
+```bash
+cd my-existing-project
+git remote add origin git@git.veltar.systems:personal/bryan/my-existing-project
+git push -u origin --all     # pushes every local branch
+git push --tags              # if you have tags worth keeping
+```
+
+The first push creates `personal/bryan/my-existing-project` on the
+server, with your full existing history intact.
+
+If the project already has a remote called `origin` pointing elsewhere
+(e.g. GitHub) and you want to keep both, use a different remote name:
+
+```bash
+git remote add gwaihir git@git.veltar.systems:personal/bryan/my-existing-project
+git push -u gwaihir --all
+```
+
+## Case B: your project isn't a git repo yet
+
+```bash
+cd my-existing-project
+git init
+git add .
+git commit -m "Initial import"
+git remote add origin git@git.veltar.systems:personal/bryan/my-existing-project
+git push -u origin master     # or main
+```
+
+## Mirroring a repo exactly (all branches, tags, refs, as-is)
+
+If you want a byte-for-byte mirror (e.g. migrating a repo wholesale)
+rather than just pushing your current checkout:
+
+```bash
+git clone --mirror <source-url> my-existing-project.git
+cd my-existing-project.git
+git push --mirror git@git.veltar.systems:personal/bryan/my-existing-project
+```
+
+## After importing
+
+Same as any other repo you create — you own it (`RW+`), you can grant
+others access with `ssh git@git.veltar.systems perms ...` (see the other
+doc), and it's private/SSH-only unless you ask an admin to add it to
+cgit (see [making-a-repo-public.md](making-a-repo-public.md)).
diff --git a/making-a-repo-public.md b/making-a-repo-public.md
new file mode 100644
index 0000000..080951c
--- /dev/null
+++ b/making-a-repo-public.md
@@ -0,0 +1,68 @@
+# Making a repo public (cgit)
+
+SSH access (gitolite) and web visibility (cgit) are **completely
+independent**. Every repo — whether created by an admin or self-created
+under `personal/<you>/...` — starts private: pushable/pullable over SSH
+by whoever gitolite grants access to, but invisible on
+`https://git.veltar.systems`.
+
+Making a repo browsable on the web is an **admin-only, server-side**
+step — it's not something you can do from a `git push`, and that's
+deliberate: it's the actual privacy boundary. Only repos explicitly
+listed get served; everything else silently doesn't exist as far as the
+web UI is concerned, regardless of who can SSH into it.
+
+If you're not an admin, ask one to do this for you (tell them the repo
+path, e.g. `personal/bryan/my-project`, and what description you want
+shown). If you are the admin, here's the process:
+
+## 1. SSH into gwaihir directly (not through gitolite — an actual shell)
+
+```bash
+ssh root@gwaihir
+```
+
+## 2. Add a stanza to `/etc/cgitrc`
+
+```
+repo.url=personal/bryan/my-project
+repo.path=/home/git/repositories/personal/bryan/my-project.git
+repo.desc=A short description shown on the repo list
+```
+
+`repo.url` is what shows up in the URL
+(`https://git.veltar.systems/personal/bryan/my-project/`) and can be
+whatever you like — it doesn't have to match the gitolite path, though
+keeping them the same avoids confusion.
+
+## 3. Reload nginx
+
+```bash
+nginx -t && systemctl reload nginx
+```
+
+That's it — no restart of cgit/fcgiwrap needed, cgit re-reads `/etc/cgitrc`
+on every request (it's a CGI process spawned fresh each time, not a
+long-running daemon).
+
+## 4. Verify
+
+```bash
+curl -s https://git.veltar.systems/ | grep my-project
+```
+
+You should see it listed on the index page, with working tree/log/diff
+links.
+
+## Un-publishing a repo
+
+Delete (or comment out) its `repo.url`/`repo.path`/`repo.desc` block from
+`/etc/cgitrc` and reload nginx the same way. This does not touch
+anything in gitolite — SSH access is unaffected either way.
+
+## A note on partial privacy
+
+If you ever want a repo browsable over HTTP but gated behind a password
+rather than either "fully public" or "fully hidden," that needs a
+separate nginx `location` block with `auth_basic` wrapping just that
+repo's path — not covered here, ask if you need it.