From f4a72a33fc67911f65e69a9d605512c8590fe8e0 Mon Sep 17 00:00:00 2001 From: jaysa68 Date: Thu, 30 Apr 2026 04:41:25 -0700 Subject: [PATCH 1/4] ignore bod notes in dev --- README.md | 4 ++++ flake.nix | 2 +- mkdocs-dev.yml | 3 +++ 3 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 mkdocs-dev.yml diff --git a/README.md b/README.md index 81089c6..431e30d 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,10 @@ ocf mkdocs real? 1. `mkdocs serve` 1. `rm -rf docs/'Board of Directors Minutes'` so it builds faster lol +### Why isn't Board of Directors visible in development? + +We have a lot of BoD notes, which makes mkdocs rebuild very slowly (20-30 seconds). The shell hook for `nix develop` runs `mkdocs serve -f mkdocs-dev.yml` which ignores the `bod` directory. Run `mkdocs serve -f mkdocs-dev` if you need to see BoD notes on localhost. + ## TODO - fix constitution links diff --git a/flake.nix b/flake.nix index 1ceaaa8..94fb1c5 100644 --- a/flake.nix +++ b/flake.nix @@ -16,7 +16,7 @@ devShells = forAllSystems (pkgs: { default = pkgs.mkShell { inputsFrom = [ self.packages.${pkgs.system}.default ]; - shellHook = "mkdocs serve"; + shellHook = "mkdocs serve -f mkdocs-dev.yml"; }; deploy = pkgs.mkShell { packages = with pkgs; [ diff --git a/mkdocs-dev.yml b/mkdocs-dev.yml new file mode 100644 index 0000000..8b996d0 --- /dev/null +++ b/mkdocs-dev.yml @@ -0,0 +1,3 @@ +INHERIT: mkdocs.yml +exclude_docs: | + bod/** From 9c55a582003c52c67cb5fbaa4e8b99d3b45ad81a Mon Sep 17 00:00:00 2001 From: jaysa68 Date: Thu, 30 Apr 2026 04:49:16 -0700 Subject: [PATCH 2/4] minor update for koi and carp --- docs/staff-docs/infrastructure/external-firewall.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/staff-docs/infrastructure/external-firewall.md b/docs/staff-docs/infrastructure/external-firewall.md index 57fc5be..8c772ad 100644 --- a/docs/staff-docs/infrastructure/external-firewall.md +++ b/docs/staff-docs/infrastructure/external-firewall.md @@ -60,7 +60,7 @@ logs there over TLS, so currently it is failing. We use Fail2Ban as part of our effort to prevent brute-force attacks or other malicious activities. Mainly, it blocks IP addresses with too many access attempts and add them to “jail“ for set amount of time. -Fail2Ban runs on death.ocf.berkeley.edu, where our main web proxy runs. +Fail2Ban runs on death.ocf.berkeley.edu, where our main web proxy runs. It also runs on `koi.ocf.berkeley.edu` and `carp.ocf.berkeley.edu` to prevent SSH spam. To whitelist IPs, add IPs to `ignoreip` in `/etc/fail2ban/jail.conf`. Example: From a3e877ae4595fdca4f6d931fd3ddfb09a90a0404 Mon Sep 17 00:00:00 2001 From: jaysa68 Date: Thu, 30 Apr 2026 07:01:34 -0700 Subject: [PATCH 3/4] some restructuring --- docs/staff-docs/.nav.yml | 1 - .../staff-docs/{ => archive}/staffvm/index.md | 0 .../{ => archive}/staffvm/ocfweb.md | 0 .../infrastructure/debian-hosts/.nav.yml | 1 + .../debian-hosts}/backporting-packages.md | 0 .../{ => debian-hosts}/github-runner.md | 0 .../infrastructure/debian-hosts/index.md | 7 ++ .../{ => debian-hosts}/jenkins.md | 0 .../{ => debian-hosts}/libvirt.md | 0 .../debian-hosts}/new-host.md | 0 .../{ => debian-hosts}/puppet.md | 3 + docs/staff-docs/infrastructure/dns/.nav.yml | 1 + .../dns}/dynamic-dns-letsencrypt-dns01.md | 0 docs/staff-docs/infrastructure/dns/index.md | 5 + .../mail/config-vhost.md} | 0 docs/staff-docs/infrastructure/mail/vhost.md | 2 +- docs/staff-docs/infrastructure/manage-chat.md | 2 +- .../infrastructure/nix-hosts/.nav.yml | 1 + .../nix-hosts/ci-cd.md} | 14 ++- .../nix-hosts}/debugging-with-nix-repl.md | 0 .../desktop-bootstrap-instructions.md | 0 .../nix-hosts}/how-to-learn-nix.md | 0 .../nix-hosts}/index.md | 0 .../infrastructure/nix-hosts/login-servers.md | 118 ++++++++++++++++++ .../nix-hosts}/new-hosts.md | 0 .../nix-hosts}/nix-on-your-computer.md | 0 .../nix-hosts}/proxmox.md | 0 .../nix-hosts}/secrets.md | 0 .../nix-hosts}/working-on-nixos-desktops.md | 0 docs/staff-docs/nix/TODO.md | 37 ------ docs/staff-docs/nix/ci.md | 12 -- docs/staff-docs/nix/modules.md | 9 -- .../class-accounts.md | 0 .../group-accounts.md | 0 .../accts-and-permissions/google-accounts.md | 22 ---- .../granting-staff-privileges.md | 28 ----- .../procedures/accts-and-permissions/index.md | 3 - docs/staff-docs/procedures/gapps.md | 44 +++---- .../procedures/printer-maintenance.md | 35 ------ docs/staff-docs/procedures/ssh-koi.md | 57 --------- docs/staff-docs/procedures/sshing-into-koi.md | 57 --------- docs/staff-docs/procedures/waste-disposal.md | 2 - 42 files changed, 167 insertions(+), 294 deletions(-) rename docs/staff-docs/{ => archive}/staffvm/index.md (100%) rename docs/staff-docs/{ => archive}/staffvm/ocfweb.md (100%) create mode 100644 docs/staff-docs/infrastructure/debian-hosts/.nav.yml rename docs/staff-docs/{procedures => infrastructure/debian-hosts}/backporting-packages.md (100%) rename docs/staff-docs/infrastructure/{ => debian-hosts}/github-runner.md (100%) create mode 100644 docs/staff-docs/infrastructure/debian-hosts/index.md rename docs/staff-docs/infrastructure/{ => debian-hosts}/jenkins.md (100%) rename docs/staff-docs/infrastructure/{ => debian-hosts}/libvirt.md (100%) rename docs/staff-docs/{procedures => infrastructure/debian-hosts}/new-host.md (100%) rename docs/staff-docs/infrastructure/{ => debian-hosts}/puppet.md (53%) create mode 100644 docs/staff-docs/infrastructure/dns/.nav.yml rename docs/staff-docs/{procedures => infrastructure/dns}/dynamic-dns-letsencrypt-dns01.md (100%) create mode 100644 docs/staff-docs/infrastructure/dns/index.md rename docs/staff-docs/{procedures/vhost.md => infrastructure/mail/config-vhost.md} (100%) create mode 100644 docs/staff-docs/infrastructure/nix-hosts/.nav.yml rename docs/staff-docs/{nix/cd.md => infrastructure/nix-hosts/ci-cd.md} (87%) rename docs/staff-docs/{nix => infrastructure/nix-hosts}/debugging-with-nix-repl.md (100%) rename docs/staff-docs/{nix => infrastructure/nix-hosts}/desktop-bootstrap-instructions.md (100%) rename docs/staff-docs/{nix => infrastructure/nix-hosts}/how-to-learn-nix.md (100%) rename docs/staff-docs/{nix => infrastructure/nix-hosts}/index.md (100%) create mode 100644 docs/staff-docs/infrastructure/nix-hosts/login-servers.md rename docs/staff-docs/{nix => infrastructure/nix-hosts}/new-hosts.md (100%) rename docs/staff-docs/{nix => infrastructure/nix-hosts}/nix-on-your-computer.md (100%) rename docs/staff-docs/{nix => infrastructure/nix-hosts}/proxmox.md (100%) rename docs/staff-docs/{nix => infrastructure/nix-hosts}/secrets.md (100%) rename docs/staff-docs/{nix => infrastructure/nix-hosts}/working-on-nixos-desktops.md (100%) delete mode 100644 docs/staff-docs/nix/TODO.md delete mode 100644 docs/staff-docs/nix/ci.md delete mode 100644 docs/staff-docs/nix/modules.md rename docs/staff-docs/procedures/{accts-and-permissions => accounts}/class-accounts.md (100%) rename docs/staff-docs/procedures/{accts-and-permissions => accounts}/group-accounts.md (100%) delete mode 100644 docs/staff-docs/procedures/accts-and-permissions/google-accounts.md delete mode 100644 docs/staff-docs/procedures/accts-and-permissions/granting-staff-privileges.md delete mode 100644 docs/staff-docs/procedures/accts-and-permissions/index.md delete mode 100644 docs/staff-docs/procedures/printer-maintenance.md delete mode 100644 docs/staff-docs/procedures/ssh-koi.md delete mode 100644 docs/staff-docs/procedures/sshing-into-koi.md delete mode 100644 docs/staff-docs/procedures/waste-disposal.md diff --git a/docs/staff-docs/.nav.yml b/docs/staff-docs/.nav.yml index 93018b1..2279a0d 100644 --- a/docs/staff-docs/.nav.yml +++ b/docs/staff-docs/.nav.yml @@ -3,5 +3,4 @@ nav: - Getting Involved: get-involved - Request Tracker (RT): rt - "*" - - Staff Virtual Machines: staffvm - archive diff --git a/docs/staff-docs/staffvm/index.md b/docs/staff-docs/archive/staffvm/index.md similarity index 100% rename from docs/staff-docs/staffvm/index.md rename to docs/staff-docs/archive/staffvm/index.md diff --git a/docs/staff-docs/staffvm/ocfweb.md b/docs/staff-docs/archive/staffvm/ocfweb.md similarity index 100% rename from docs/staff-docs/staffvm/ocfweb.md rename to docs/staff-docs/archive/staffvm/ocfweb.md diff --git a/docs/staff-docs/infrastructure/debian-hosts/.nav.yml b/docs/staff-docs/infrastructure/debian-hosts/.nav.yml new file mode 100644 index 0000000..811574a --- /dev/null +++ b/docs/staff-docs/infrastructure/debian-hosts/.nav.yml @@ -0,0 +1 @@ +title: Debian Hosts diff --git a/docs/staff-docs/procedures/backporting-packages.md b/docs/staff-docs/infrastructure/debian-hosts/backporting-packages.md similarity index 100% rename from docs/staff-docs/procedures/backporting-packages.md rename to docs/staff-docs/infrastructure/debian-hosts/backporting-packages.md diff --git a/docs/staff-docs/infrastructure/github-runner.md b/docs/staff-docs/infrastructure/debian-hosts/github-runner.md similarity index 100% rename from docs/staff-docs/infrastructure/github-runner.md rename to docs/staff-docs/infrastructure/debian-hosts/github-runner.md diff --git a/docs/staff-docs/infrastructure/debian-hosts/index.md b/docs/staff-docs/infrastructure/debian-hosts/index.md new file mode 100644 index 0000000..3d6e133 --- /dev/null +++ b/docs/staff-docs/infrastructure/debian-hosts/index.md @@ -0,0 +1,7 @@ +--- +title: Debian Hosts +--- + +Information about our remaining debian hosts. We want to finish migrating the services on these to NixOS VMs or to our k8s cluster soon. + +Our debian hosts follow the old natural disasters naming scheme. Old debian desktops were also named after disasters. Now, nix desktops are named after cats from Neko Atsume, and nix hosts are named after fish. diff --git a/docs/staff-docs/infrastructure/jenkins.md b/docs/staff-docs/infrastructure/debian-hosts/jenkins.md similarity index 100% rename from docs/staff-docs/infrastructure/jenkins.md rename to docs/staff-docs/infrastructure/debian-hosts/jenkins.md diff --git a/docs/staff-docs/infrastructure/libvirt.md b/docs/staff-docs/infrastructure/debian-hosts/libvirt.md similarity index 100% rename from docs/staff-docs/infrastructure/libvirt.md rename to docs/staff-docs/infrastructure/debian-hosts/libvirt.md diff --git a/docs/staff-docs/procedures/new-host.md b/docs/staff-docs/infrastructure/debian-hosts/new-host.md similarity index 100% rename from docs/staff-docs/procedures/new-host.md rename to docs/staff-docs/infrastructure/debian-hosts/new-host.md diff --git a/docs/staff-docs/infrastructure/puppet.md b/docs/staff-docs/infrastructure/debian-hosts/puppet.md similarity index 53% rename from docs/staff-docs/infrastructure/puppet.md rename to docs/staff-docs/infrastructure/debian-hosts/puppet.md index 6b28626..e0b4978 100644 --- a/docs/staff-docs/infrastructure/puppet.md +++ b/docs/staff-docs/infrastructure/debian-hosts/puppet.md @@ -6,4 +6,7 @@ The puppetmaster is [lightning][servers]. Instructions on making, testing, and deploying changes to Puppet are located at the [Git repository](https://github.com/ocf/puppet) on GitHub. +We only use puppet on our old debian hosts. We are trying to migrate many of these hosts to Nix or to our k8s cluster. Nix hosts handle deploying changes through [self-hosted github actions runners](../nix/ci-cd.md) rather than puppet. + [servers]: https://www.ocf.berkeley.edu/docs/staff/backend/servers/ + diff --git a/docs/staff-docs/infrastructure/dns/.nav.yml b/docs/staff-docs/infrastructure/dns/.nav.yml new file mode 100644 index 0000000..abef1a1 --- /dev/null +++ b/docs/staff-docs/infrastructure/dns/.nav.yml @@ -0,0 +1 @@ +title: DNS diff --git a/docs/staff-docs/procedures/dynamic-dns-letsencrypt-dns01.md b/docs/staff-docs/infrastructure/dns/dynamic-dns-letsencrypt-dns01.md similarity index 100% rename from docs/staff-docs/procedures/dynamic-dns-letsencrypt-dns01.md rename to docs/staff-docs/infrastructure/dns/dynamic-dns-letsencrypt-dns01.md diff --git a/docs/staff-docs/infrastructure/dns/index.md b/docs/staff-docs/infrastructure/dns/index.md new file mode 100644 index 0000000..44362e5 --- /dev/null +++ b/docs/staff-docs/infrastructure/dns/index.md @@ -0,0 +1,5 @@ +--- +title: DNS +--- + +How DNS works (and often, does not work) at the OCF diff --git a/docs/staff-docs/procedures/vhost.md b/docs/staff-docs/infrastructure/mail/config-vhost.md similarity index 100% rename from docs/staff-docs/procedures/vhost.md rename to docs/staff-docs/infrastructure/mail/config-vhost.md diff --git a/docs/staff-docs/infrastructure/mail/vhost.md b/docs/staff-docs/infrastructure/mail/vhost.md index b94a8ef..c049cc2 100644 --- a/docs/staff-docs/infrastructure/mail/vhost.md +++ b/docs/staff-docs/infrastructure/mail/vhost.md @@ -47,5 +47,5 @@ clients to send as a vhost address. (See `/etc/pam.d/smtp` and ## How do I add mail hosting to a group? -See [here](../../procedures/vhost.md#mail). +See [here](../config-vhost/). diff --git a/docs/staff-docs/infrastructure/manage-chat.md b/docs/staff-docs/infrastructure/manage-chat.md index 97875ad..4bfba00 100644 --- a/docs/staff-docs/infrastructure/manage-chat.md +++ b/docs/staff-docs/infrastructure/manage-chat.md @@ -1,5 +1,5 @@ --- -title: Managing Chat +title: Managing OCF Chat --- config on host stored in `/etc/ergo.yaml`. should pull from github diff --git a/docs/staff-docs/infrastructure/nix-hosts/.nav.yml b/docs/staff-docs/infrastructure/nix-hosts/.nav.yml new file mode 100644 index 0000000..2468dc9 --- /dev/null +++ b/docs/staff-docs/infrastructure/nix-hosts/.nav.yml @@ -0,0 +1 @@ +title: Nix Hosts diff --git a/docs/staff-docs/nix/cd.md b/docs/staff-docs/infrastructure/nix-hosts/ci-cd.md similarity index 87% rename from docs/staff-docs/nix/cd.md rename to docs/staff-docs/infrastructure/nix-hosts/ci-cd.md index c2696d6..c322a0b 100644 --- a/docs/staff-docs/nix/cd.md +++ b/docs/staff-docs/infrastructure/nix-hosts/ci-cd.md @@ -1,13 +1,21 @@ --- -title: Deploy +title: Github Actions CI/CD --- -TODO: make this fancy with generators (see https://github.com/oddlama/agenix-rekey), privkey goes into secrets dir, pubkey automatically generated and placed on host by nix. +## adding a runner + +1. edit `spike.nix` in `hosts/servers`, add new entry in `runners`. pattern match, look at `options.nix` for github-actions module +2. generate github personal access token, as per description in `options.nix` of github-actions for OCF org +[TODO insert docs for github personal access token here] +3. in the repo of the service, create the `github/workflows/build.yml` file -we need the runner(s) to have permission to place files & make changes on the host which will run the service! ## if SSH is necessary for deploy: +TODO: make this fancy with generators (see https://github.com/oddlama/agenix-rekey), privkey goes into secrets dir, pubkey automatically generated and placed on host by nix. + +we need the runner(s) to have permission to place files & make changes on the host which will run the service! + ### client (workflow) to server (amethyst) 1. generate SSH keypair diff --git a/docs/staff-docs/nix/debugging-with-nix-repl.md b/docs/staff-docs/infrastructure/nix-hosts/debugging-with-nix-repl.md similarity index 100% rename from docs/staff-docs/nix/debugging-with-nix-repl.md rename to docs/staff-docs/infrastructure/nix-hosts/debugging-with-nix-repl.md diff --git a/docs/staff-docs/nix/desktop-bootstrap-instructions.md b/docs/staff-docs/infrastructure/nix-hosts/desktop-bootstrap-instructions.md similarity index 100% rename from docs/staff-docs/nix/desktop-bootstrap-instructions.md rename to docs/staff-docs/infrastructure/nix-hosts/desktop-bootstrap-instructions.md diff --git a/docs/staff-docs/nix/how-to-learn-nix.md b/docs/staff-docs/infrastructure/nix-hosts/how-to-learn-nix.md similarity index 100% rename from docs/staff-docs/nix/how-to-learn-nix.md rename to docs/staff-docs/infrastructure/nix-hosts/how-to-learn-nix.md diff --git a/docs/staff-docs/nix/index.md b/docs/staff-docs/infrastructure/nix-hosts/index.md similarity index 100% rename from docs/staff-docs/nix/index.md rename to docs/staff-docs/infrastructure/nix-hosts/index.md diff --git a/docs/staff-docs/infrastructure/nix-hosts/login-servers.md b/docs/staff-docs/infrastructure/nix-hosts/login-servers.md new file mode 100644 index 0000000..5aa57b7 --- /dev/null +++ b/docs/staff-docs/infrastructure/nix-hosts/login-servers.md @@ -0,0 +1,118 @@ +--- +title: Login Servers +--- + +## Public login server (carp) + +## Staff login server (koi) + +When contributing to the OCF codebase, you will need some way of running and +testing your code. Most of our applications cannot be run on a personal +machine--they need to be run on OCF infrastructure. For most projects we +recommend doing all development from `koi`, a server available to all +staff. Our [Kubernetes server](../infrastructure/kubernetes/index.md) is also +accessible from `koi`. + +## Before you begin +You need to be on staff to log into the server. If you're not sure whether or +not you're on staff, try logging in. If this doesn't work, talk to a staff +member and we can add you! All are welcome and encouraged to join. + +## Logging in +To log in, open a terminal window and type in: + +```bash +ssh username@koi.ocf.berkeley.edu +``` + +For more instructions, see the [SSH docs](../../user-docs/services/shell/index.md). You should +replace `ssh.ocf.berkeley.edu` with `koi.ocf.berkeley.edu`. + +## Setting up SSH Keys + +You can log in to `koi` like normal (`ssh $USER@koi.ocf.berkeley.edu`) with your username and password, but should seriously consider creating and uploading an SSH key so that you don't need to type a password when logging in anymore. + +First, check if you have an SSH key. You can do this by checking `~/.ssh` on your laptop. If you see files named `id_rsa` or `id_ed25519` (these are private keys and should never leave your computer, the public keys are in `id_rsa.pub` or `id_ed25519.pub`), then you already have an SSH key! If not, create an SSH key like… + +```bash +# Accept all default values when prompted. You can set a password on the key if you want. +ssh-keygen -t ed25519 -C "$USER@ocf.berkeley.edu" +``` + +Then, to upload your public key to a server (e.x. koi), do… + +```bash +ssh-copy-id koi.ocf.berkeley.edu +``` + +## Configuring your SSH Config + +Paste this into `~/.ssh/config`, and you'll be able to ssh into any OCF host with just `ssh $HOSTNAME.ocf`. + +```bash +Host koi.ocf + ProxyJump none + Port 22 + # This will allow koi to sign things with your *private* key! + # Only uncomment this if you understand the risks and/or have an SSH agent + # that will interactively prompt you about when your key is being used. + # ForwardAgent yes + +Host *.ocf + Hostname %h.berkeley.edu + ProxyJump koi.ocf +``` + +## Things you can do on `koi` + +### Administration scripts + +Some scripts, such as ones used to create group accounts and refund printing +quotas, are available on `koi`. Learn more about these in the scripts +section of [staff documentation](../index.md). + +### Development and Testing +You can `git clone` OCF repositories and run them on `koi`. An example +for `ocfweb`: + +```bash +git clone https://github.com/ocf/ocfweb # clone the repository +cd ocfweb # change directory into the repository + +... make changes ... + +make test # run tests to make sure everything is working +make dev # start a development server and see your changes live +``` + +### Kubernetes +To access Kubernetes, simply run `kubectl` commands. See the [Kubernetes +documentation][kubernetes-basics] for more information. + +Note that staff only have viewing permissions for the cluster. Interested +stafferse can request write access to a development namespace by talking to a +root staffer. + +[kubernetes-basics]: https://kubernetes.io/docs/tutorials/kubernetes-basics/ + +## Troubleshooting + +### Cannot delete characters or use keyboard shortcuts + +This may occur if you're using a terminal emulator on the machine you're using to SSH that sets a custom `TERM` environment variable. If you're using something xterm-compatible (e.x. `kitty`, `alacritty`), then first check the value of `TERM` as follows… + +```bash +❯ echo $TERM +xterm-kitty +``` + +And then add this to your `~/.bashrc` on the remote end (replacing `xterm-kitty` with the `TERM` variable you got in the first step)… + +```bash +if [[ $TERM = "xterm-kitty" ]]; then export TERM=xterm-256color; fi +``` + +This will make the remote end treat your terminal as if it's xterm, which should make your keyboard shortcuts and backspace work again. + +The proper fix for this is to find the package on the remote end that provides support for your terminal emulator, and install it. For example, the `kitty-terminfo` package on Debian is installed on all OCF machines so that if you use kitty over SSH, your terminal will work. If you'd like to fix your terminal just for your user, find the appropriate terminfo file and place it in `~/.local/share/terminfo/`. + diff --git a/docs/staff-docs/nix/new-hosts.md b/docs/staff-docs/infrastructure/nix-hosts/new-hosts.md similarity index 100% rename from docs/staff-docs/nix/new-hosts.md rename to docs/staff-docs/infrastructure/nix-hosts/new-hosts.md diff --git a/docs/staff-docs/nix/nix-on-your-computer.md b/docs/staff-docs/infrastructure/nix-hosts/nix-on-your-computer.md similarity index 100% rename from docs/staff-docs/nix/nix-on-your-computer.md rename to docs/staff-docs/infrastructure/nix-hosts/nix-on-your-computer.md diff --git a/docs/staff-docs/nix/proxmox.md b/docs/staff-docs/infrastructure/nix-hosts/proxmox.md similarity index 100% rename from docs/staff-docs/nix/proxmox.md rename to docs/staff-docs/infrastructure/nix-hosts/proxmox.md diff --git a/docs/staff-docs/nix/secrets.md b/docs/staff-docs/infrastructure/nix-hosts/secrets.md similarity index 100% rename from docs/staff-docs/nix/secrets.md rename to docs/staff-docs/infrastructure/nix-hosts/secrets.md diff --git a/docs/staff-docs/nix/working-on-nixos-desktops.md b/docs/staff-docs/infrastructure/nix-hosts/working-on-nixos-desktops.md similarity index 100% rename from docs/staff-docs/nix/working-on-nixos-desktops.md rename to docs/staff-docs/infrastructure/nix-hosts/working-on-nixos-desktops.md diff --git a/docs/staff-docs/nix/TODO.md b/docs/staff-docs/nix/TODO.md deleted file mode 100644 index c4b9bb8..0000000 --- a/docs/staff-docs/nix/TODO.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: TODO ---- - -Things we probably should get to at some point. If you're adding things to this -list and especially the starter tasks try to link to the relevant host config -and maybe some general direction if you know what needs to be done (at least in principle). - -## Starter Tasks -Good first steps to get learn your way around the repo and pick up the nix language. - -### Fix / Improve OCF TV -[Tornado](https://github.com/ocf/nix/tree/main/hosts/misc/tornado.nix) is the host that keeps the labmap up on the TV. It runs [sway](https://swaywm.org/) -a tiling window manager and allows staff to control it via a VNC connection -by running `ocf-tv` on any of the lab desktops. - -#### Server -WayVNC is started as a command at the end of the sway config at the moment and this -sometimes causes the VNC server to die if a client disconnects uncleanly, needing sway -to be reloaded. The only way to do this when the VNC server is down is a reboot which really -isn't ideal. We use a module system in Nix that allows us to reuse code across hosts and - -We have (had) - -### Make Print Queue Real -This might be more of a physical plug shit in and check if it works task but it's a task nonetheless. -The monitor is no longer there and it could be because it wasn't working and someone decided to remove -it. The system in question is [overheat](https://github.com/ocf/nix/tree/main/hosts/overheat.nix) a -raspberry pi 4 that you should be able to find near / behind papercut. - -## Not so Starter Tasks - -### Docs -yup... - -### CD - diff --git a/docs/staff-docs/nix/ci.md b/docs/staff-docs/nix/ci.md deleted file mode 100644 index 7089d76..0000000 --- a/docs/staff-docs/nix/ci.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: OCF CI ---- - -hostname: spike - -## adding a runner - -1. edit `spike.nix` in `hosts/servers`, add new entry in `runners`. pattern match, look at `options.nix` for github-actions module -2. generate github personal access token, as per description in `options.nix` of github-actions for OCF org -[TODO insert docs for github personal access token here] -3. in the repo of the service, create the `github/workflows/build.yml` file diff --git a/docs/staff-docs/nix/modules.md b/docs/staff-docs/nix/modules.md deleted file mode 100644 index 83b55bd..0000000 --- a/docs/staff-docs/nix/modules.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Modules ---- - -TODO: description of a nix module, when it is appropriate to use/create one for the OCF - -## Creating a Module - - diff --git a/docs/staff-docs/procedures/accts-and-permissions/class-accounts.md b/docs/staff-docs/procedures/accounts/class-accounts.md similarity index 100% rename from docs/staff-docs/procedures/accts-and-permissions/class-accounts.md rename to docs/staff-docs/procedures/accounts/class-accounts.md diff --git a/docs/staff-docs/procedures/accts-and-permissions/group-accounts.md b/docs/staff-docs/procedures/accounts/group-accounts.md similarity index 100% rename from docs/staff-docs/procedures/accts-and-permissions/group-accounts.md rename to docs/staff-docs/procedures/accounts/group-accounts.md diff --git a/docs/staff-docs/procedures/accts-and-permissions/google-accounts.md b/docs/staff-docs/procedures/accts-and-permissions/google-accounts.md deleted file mode 100644 index 2cb029a..0000000 --- a/docs/staff-docs/procedures/accts-and-permissions/google-accounts.md +++ /dev/null @@ -1,22 +0,0 @@ -# Google Accounts - -The OCF has its own Google Apps deployment, which we mainly use for GDrive and GMail. While it's possible to use `@berkeley.edu` Google accounts for these (`@ocf.berkeley.edu` emails redirect to Berkeley Google accounts by default), most active staffers choose to have a dedicated account because: - -* It allows for nicer integration with our Google Drive folders. -* It makes it easier to send emails from the `ocf.berkeley.edu` domain, which is good if you want to send an email while representing the OCF. -* It can be useful to have a separation between OCF and Berkeley accounts. - -## Making an account - -Google Apps accounts are available upon request for OCF staff members, and are granted at SM discretion. Upon getting one, staffers should be aware that OCF emails will be sent to the new account instead of the Berkeley account that they're used to. - -Making a new account requires Google Admin privileges. - - -1. Go to [admin.google.com](http://admin.google.com), click on the "Users" section of the Admin panel, and press the '+' button. -2. Fill in the first and last name of the user, and make sure their email address matches their OCF username. -3. Update the user's `mail` attribute in LDAP to use Google Apps (`kinit YOUR_USER/admin ldapvi uid=THEIR_USER`) and change it to `usernamehere@g.ocf.berkeley.edu`. - - - 1. **The** `g.` **in the domain is critical; omitting it can cause email delivery loops in our system!** -4. Add the user to the appropriate Google groups, and (if needed) add them as members on the OCF Staff shared drive. \ No newline at end of file diff --git a/docs/staff-docs/procedures/accts-and-permissions/granting-staff-privileges.md b/docs/staff-docs/procedures/accts-and-permissions/granting-staff-privileges.md deleted file mode 100644 index 0475cf1..0000000 --- a/docs/staff-docs/procedures/accts-and-permissions/granting-staff-privileges.md +++ /dev/null @@ -1,28 +0,0 @@ -# Granting Staff Privileges - -# ocfstaff - - -1. Run this command on any OCF machine, which will open your `$EDITOR`. - -```bash -kinit $USER/admin ldapvi cn=ocfstaff -``` - - -2. Add or remove the line `memberUid: staffusername` within the file (your placement doesn't matter, the list sorts itself alphabetically later). - - - 1. Be VERY VERY careful to not hit `dG` or something like that in vim, which will delete the whole file. We have backups (and have had to do this in the past), but don't rely on them -- be careful! - 2. Make sure there are no empty lines in the entry, and that the first line with the object DN (something like `0 cn=ocfstaff,ou=Groups,dc=OCF,dc=Berkeley,dc=EDU`) isn't changed - otherwise ldapvi gets confused, and might clear the object. -3. (Optional) Their groups won't update on all of the servers until the daily cronjob runs. If they need the `ocfstaff` role on a specific server immediately, then [SSH](/doc/ssh-iQbr9ALK7Z) into that server and run the following commands. - - ```bash - sudo nss_updatedb ldap - # may fail, but probably okay if it does fail - sudo systemctl restart unscd - ``` - -# ocfroot - -Instructions and considerations for adding someone as a new root staffer are in the secret documentation. If you are root you should know where that is, or whoever added you to root didn't follow procedure and needs to be (nicely) yelled at. \ No newline at end of file diff --git a/docs/staff-docs/procedures/accts-and-permissions/index.md b/docs/staff-docs/procedures/accts-and-permissions/index.md deleted file mode 100644 index 31f346c..0000000 --- a/docs/staff-docs/procedures/accts-and-permissions/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# Accounts and Permissions - -This section broadly describes how you create / manage accounts at the OCF on the various platforms that we use. \ No newline at end of file diff --git a/docs/staff-docs/procedures/gapps.md b/docs/staff-docs/procedures/gapps.md index 9cec8b8..bef074f 100644 --- a/docs/staff-docs/procedures/gapps.md +++ b/docs/staff-docs/procedures/gapps.md @@ -1,30 +1,22 @@ ---- -title: Making OCF Google Apps Accounts ---- +# Google Accounts -The OCF has its own Google Apps deployment, which we mainly use for GDrive and -GMail. While it's possible to use Calnet accounts for these (ocf.berkeley.edu -emails redirect to Calnet by default), most active staffers choose to have a -dedicated account because: +The OCF has its own Google Apps deployment, which we mainly use for GDrive and GMail. While it's possible to use `@berkeley.edu` Google accounts for these (`@ocf.berkeley.edu` emails redirect to Berkeley Google accounts by default), most active staffers choose to have a dedicated account because: -* It allows for nicer integration with our Google Drive folders -* It makes it easier to send emails from the ocf.berkeley.edu domain, which is -good if you want to send an email while representing the OCF -* It can be useful to have a separation between OCF and Calnet accounts. +* It allows for nicer integration with our Google Drive folders. +* It makes it easier to send emails from the `ocf.berkeley.edu` domain, which is good if you want to send an email while representing the OCF. +* It can be useful to have a separation between OCF and Berkeley accounts. ## Making an account -Google Apps accounts are available upon request for OCF staff members, and are -granted at SM discretion. Upon getting one, staffers should be aware that OCF -emails will be sent to the new account instead of the Calnet account that -they're used to. - -Making a new account requires Google Admin privileges: - -1. Go to admin.google.com, click on the "Users" section of the Admin panel, and -press the '+' button. -2. Fill in the first and last name of the user, and make sure their email -address matches their OCF username. -3. Update the user's `mail` attribute in LDAP to use Google Apps: `kinit -you/admin uid=usernamehere`. Change it to `usernamehere@g.ocf.berkeley.edu`. -**The `g.` in the domain is critical; omitting it can cause email delivery -loops in our system!** + +Google Apps accounts are available upon request for OCF staff members, and are granted at SM discretion. Upon getting one, staffers should be aware that OCF emails will be sent to the new account instead of the Berkeley account that they're used to. + +Making a new account requires Google Admin privileges. + + +1. Go to [admin.google.com](http://admin.google.com), click on the "Users" section of the Admin panel, and press the '+' button. +2. Fill in the first and last name of the user, and make sure their email address matches their OCF username. +3. Update the user's `mail` attribute in LDAP to use Google Apps (`kinit YOUR_USER/admin ldapvi uid=THEIR_USER`) and change it to `usernamehere@g.ocf.berkeley.edu`. + + + 1. **The** `g.` **in the domain is critical; omitting it can cause email delivery loops in our system!** +4. Add the user to the appropriate Google groups, and (if needed) add them as members on the OCF Staff shared drive. diff --git a/docs/staff-docs/procedures/printer-maintenance.md b/docs/staff-docs/procedures/printer-maintenance.md deleted file mode 100644 index bba3625..0000000 --- a/docs/staff-docs/procedures/printer-maintenance.md +++ /dev/null @@ -1,35 +0,0 @@ -# Printer Maintenance - -## General Information - -* As of Fall 2023, we use Quill.com for our paper. See [purchase request](https://callink.berkeley.edu/finance/ocf/requests/purchase/1375196) for last membership renewal. - - -## Toner Cartridge Disposal - -* \ - - -## FAQ - -### **Nothing shows when clicking print.** - -Check what print jobs are currently lined up. Delete duplicates. - -### **Pagefault isn't printing.** - -cope - -### **The screen above the printer isn't correct.** - -Restart printhost (which runs on old kube) with the following command: - -```bash -kubectl -n app-printlist rollout restart deploy/deployment -``` - -### **~~Page comes out completely black.~~** - -~~Make sure they have the file saved as a PDF, and open it in Okular. Click print, then to go to options, PDF options, and check the box for "Force rasterization". Try printing again now.~~ - -No longer an issue as of Fall 2023. Turned on force rasterize by default. \ No newline at end of file diff --git a/docs/staff-docs/procedures/ssh-koi.md b/docs/staff-docs/procedures/ssh-koi.md deleted file mode 100644 index bb89fc3..0000000 --- a/docs/staff-docs/procedures/ssh-koi.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: SSHing into Koi ---- - -When contributing to the OCF codebase, you will need some way of running and -testing your code. Most of our applications cannot be run on a personal -machine--they need to be run on OCF infrastructure. For most projects we -recommend doing all development from `koi`, a server available to all -staff. Our [Kubernetes server](../infrastructure/kubernetes/index.md) is also -accessible from `koi`. - -## Before you begin -You need to be on staff to log into the server. If you're not sure whether or -not you're on staff, try logging in. If this doesn't work, talk to a staff -member and we can add you! All are welcome and encouraged to join. - -## Logging in -To log in, open a terminal window and type in: - -```bash -ssh username@koi.ocf.berkeley.edu -``` - -For more instructions, see the [SSH docs](../../user-docs/services/shell/index.md). You should -replace `ssh.ocf.berkeley.edu` with `koi.ocf.berkeley.edu`. - -## Things you can do on `koi` - -### Administration scripts - -Some scripts, such as ones used to create group accounts and refund printing -quotas, are available on `koi`. Learn more about these in the scripts -section of [staff documentation](../index.md). - -### Development and Testing -You can `git clone` OCF repositories and run them on `koi`. An example -for `ocfweb`: - -```bash -git clone https://github.com/ocf/ocfweb # clone the repository -cd ocfweb # change directory into the repository - -... make changes ... - -make test # run tests to make sure everything is working -make dev # start a development server and see your changes live -``` - -### Kubernetes -To access Kubernetes, simply run `kubectl` commands. See the [Kubernetes -documentation][kubernetes-basics] for more information. - -Note that staff only have viewing permissions for the cluster. Interested -stafferse can request write access to a development namespace by talking to a -root staffer. - -[kubernetes-basics]: https://kubernetes.io/docs/tutorials/kubernetes-basics/ diff --git a/docs/staff-docs/procedures/sshing-into-koi.md b/docs/staff-docs/procedures/sshing-into-koi.md deleted file mode 100644 index 7e6d954..0000000 --- a/docs/staff-docs/procedures/sshing-into-koi.md +++ /dev/null @@ -1,57 +0,0 @@ -# SSHing into Koi - -As an OCF staff member, a lot of what you may need to do may need to happen on an OCF machine. The machine set aside for this is `koi`. You can login to it like normal `ssh $USER@koi.ocf.berkeley.edu` with your username and password, but should seriously consider creating and uploading an SSH key so that you don't need to type a password when logging in anymore. - -## Setting up SSH Keys - -First, check if you have an SSH key. You can do this by checking `~/.ssh` on your laptop. If you see files named `id_rsa` or `id_ed25519` (these are private keys and should never leave your computer, the public keys are in `id_rsa.pub` or `id_ed25519.pub`), then you already have an SSH key! If not, create an SSH key like… - -```bash -# Accept all default values when prompted. You can set a password on the key if you want. -ssh-keygen -t ed25519 -C "$USER@ocf.berkeley.edu" -``` - -Then, to upload your public key to a server (e.x. koi), do… - -```bash -ssh-copy-id koi.ocf.berkeley.edu -``` - -## Configuring your SSH Config - -Paste this into `~/.ssh/config`, and you'll be able to ssh into any OCF host with just `ssh $HOSTNAME.ocf`. - -```bash -Host koi.ocf - ProxyJump none - Port 22 - # This will allow koi to sign things with your *private* key! - # Only uncomment this if you understand the risks and/or have an SSH agent - # that will interactively prompt you about when your key is being used. - # ForwardAgent yes - -Host *.ocf - Hostname %h.berkeley.edu - ProxyJump koi.ocf -``` - -## Troubleshooting - -### Cannot delete characters or use keyboard shortcuts - -This may occur if you're using a terminal emulator on the machine you're using to SSH that sets a custom `TERM` environment variable. If you're using something xterm-compatible (e.x. `kitty`, `alacritty`), then first check the value of `TERM` as follows… - -```bash -❯ echo $TERM -xterm-kitty -``` - -And then add this to your `~/.bashrc` on the remote end (replacing `xterm-kitty` with the `TERM` variable you got in the first step)… - -```bash -if [[ $TERM = "xterm-kitty" ]]; then export TERM=xterm-256color; fi -``` - -This will make the remote end treat your terminal as if it's xterm, which should make your keyboard shortcuts and backspace work again. - -The proper fix for this is to find the package on the remote end that provides support for your terminal emulator, and install it. For example, the `kitty-terminfo` package on Debian is installed on all OCF machines so that if you use kitty over SSH, your terminal will work. If you'd like to fix your terminal just for your user, find the appropriate terminfo file and place it in `~/.local/share/terminfo/`. \ No newline at end of file diff --git a/docs/staff-docs/procedures/waste-disposal.md b/docs/staff-docs/procedures/waste-disposal.md deleted file mode 100644 index 8ad031a..0000000 --- a/docs/staff-docs/procedures/waste-disposal.md +++ /dev/null @@ -1,2 +0,0 @@ -# Waste Disposal - From 04a96db375740136f24eecee073cb99dcbe10a68 Mon Sep 17 00:00:00 2001 From: jaysa68 Date: Thu, 30 Apr 2026 08:27:19 -0700 Subject: [PATCH 4/4] reorganization --- .../{procedures => }/accounts/alumni-reset.md | 0 .../{procedures => }/accounts/association.md | 0 .../accounts/class-accounts.md | 0 .../accounts/group-accounts.md | 9 ++-- .../{procedures => }/accounts/index.md | 0 .../{procedures => }/accounts/renaming.md | 0 .../debian-staff-vms.md} | 0 docs/staff-docs/{procedures => }/dmca.md | 0 docs/staff-docs/editing-docs/.nav.yml | 1 + .../{procedures => editing-docs}/bod-notes.md | 0 .../editing-docs.md => editing-docs/index.md} | 0 docs/staff-docs/{procedures => }/gapps.md | 0 .../get-involved/staff-privileges/.nav.yml | 1 + .../staff-privileges}/granting-privileges.md | 0 .../index.md} | 0 .../debian-hosts}/installing-updates.md | 0 .../debian-hosts}/live-resize.md | 0 .../debian-hosts}/restarting-services.md | 0 .../debian-hosts}/setting-up-lacp.md | 0 .../debian-hosts}/setting-up-mdraid.md | 0 docs/staff-docs/infrastructure/decal/index.md | 7 +++ .../dns}/new-asuc-subdomain.md | 0 .../{procedures => infrastructure/dns}/ssl.md | 0 .../dns}/updating-dns-records.md | 0 docs/staff-docs/infrastructure/hpc/.nav.yml | 1 + .../hpc/add-hpc-users.md} | 0 .../mail}/opstaff-email.md | 0 docs/staff-docs/infrastructure/nfs/.nav.yml | 1 + .../nfs}/user-quotas.md | 0 .../nix-hosts/creating-nix-hosts/.nav.yml | 1 + .../desktop-bootstrap-instructions.md | 0 .../index.md} | 2 +- .../nix-hosts/creating-nix-hosts/staff-vm.md | 13 ++++++ .../infrastructure/nix-hosts/index.md | 12 ++++-- .../nix-hosts/nix-on-your-computer.md | 12 ------ ...{how-to-learn-nix.md => njha-nix-guide.md} | 4 +- .../infrastructure/printing/index.md | 5 +++ .../printing/maintenance.md} | 0 .../{ => printing}/printhost.md | 0 .../process-accounting.md | 0 .../web-hosting}/fix-compromised-wordpress.md | 0 .../infrastructure/web-hosting/index.md | 7 +++ docs/staff-docs/procedures/.nav.yml | 3 -- docs/staff-docs/procedures/handoff.md | 43 ------------------- .../procedures/how-to-request-a-purchase.md | 24 ----------- docs/staff-docs/procedures/index.md | 5 --- docs/staff-docs/procedures/sufmo-access.md | 15 ------- .../procedures/volunteer-staff-hours-faq.md | 25 ----------- .../basic-domain-request-template.md | 0 .../i-need-something-with-berkeleyedu.md | 0 .../{procedures/rt => rt/rt-guide}/index.md | 0 .../rt-guide}/virtual-hosting-request.md | 0 52 files changed, 54 insertions(+), 137 deletions(-) rename docs/staff-docs/{procedures => }/accounts/alumni-reset.md (100%) rename docs/staff-docs/{procedures => }/accounts/association.md (100%) rename docs/staff-docs/{procedures => }/accounts/class-accounts.md (100%) rename docs/staff-docs/{procedures => }/accounts/group-accounts.md (87%) rename docs/staff-docs/{procedures => }/accounts/index.md (100%) rename docs/staff-docs/{procedures => }/accounts/renaming.md (100%) rename docs/staff-docs/{procedures/staff-vms.md => archive/debian-staff-vms.md} (100%) rename docs/staff-docs/{procedures => }/dmca.md (100%) create mode 100644 docs/staff-docs/editing-docs/.nav.yml rename docs/staff-docs/{procedures => editing-docs}/bod-notes.md (100%) rename docs/staff-docs/{procedures/editing-docs.md => editing-docs/index.md} (100%) rename docs/staff-docs/{procedures => }/gapps.md (100%) create mode 100644 docs/staff-docs/get-involved/staff-privileges/.nav.yml rename docs/staff-docs/{procedures => get-involved/staff-privileges}/granting-privileges.md (100%) rename docs/staff-docs/get-involved/{staff-privileges.md => staff-privileges/index.md} (100%) rename docs/staff-docs/{procedures => infrastructure/debian-hosts}/installing-updates.md (100%) rename docs/staff-docs/{procedures => infrastructure/debian-hosts}/live-resize.md (100%) rename docs/staff-docs/{procedures => infrastructure/debian-hosts}/restarting-services.md (100%) rename docs/staff-docs/{procedures => infrastructure/debian-hosts}/setting-up-lacp.md (100%) rename docs/staff-docs/{procedures => infrastructure/debian-hosts}/setting-up-mdraid.md (100%) create mode 100644 docs/staff-docs/infrastructure/decal/index.md rename docs/staff-docs/{procedures => infrastructure/dns}/new-asuc-subdomain.md (100%) rename docs/staff-docs/{procedures => infrastructure/dns}/ssl.md (100%) rename docs/staff-docs/{procedures => infrastructure/dns}/updating-dns-records.md (100%) create mode 100644 docs/staff-docs/infrastructure/hpc/.nav.yml rename docs/staff-docs/{procedures/hpc.md => infrastructure/hpc/add-hpc-users.md} (100%) rename docs/staff-docs/{procedures => infrastructure/mail}/opstaff-email.md (100%) create mode 100644 docs/staff-docs/infrastructure/nfs/.nav.yml rename docs/staff-docs/{procedures => infrastructure/nfs}/user-quotas.md (100%) create mode 100644 docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/.nav.yml rename docs/staff-docs/infrastructure/nix-hosts/{ => creating-nix-hosts}/desktop-bootstrap-instructions.md (100%) rename docs/staff-docs/infrastructure/nix-hosts/{new-hosts.md => creating-nix-hosts/index.md} (99%) create mode 100644 docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/staff-vm.md delete mode 100644 docs/staff-docs/infrastructure/nix-hosts/nix-on-your-computer.md rename docs/staff-docs/infrastructure/nix-hosts/{how-to-learn-nix.md => njha-nix-guide.md} (98%) create mode 100644 docs/staff-docs/infrastructure/printing/index.md rename docs/staff-docs/{procedures/printing.md => infrastructure/printing/maintenance.md} (100%) rename docs/staff-docs/infrastructure/{ => printing}/printhost.md (100%) rename docs/staff-docs/{procedures => infrastructure}/process-accounting.md (100%) rename docs/staff-docs/{procedures => infrastructure/web-hosting}/fix-compromised-wordpress.md (100%) create mode 100644 docs/staff-docs/infrastructure/web-hosting/index.md delete mode 100644 docs/staff-docs/procedures/.nav.yml delete mode 100644 docs/staff-docs/procedures/handoff.md delete mode 100644 docs/staff-docs/procedures/how-to-request-a-purchase.md delete mode 100644 docs/staff-docs/procedures/index.md delete mode 100644 docs/staff-docs/procedures/sufmo-access.md delete mode 100644 docs/staff-docs/procedures/volunteer-staff-hours-faq.md rename docs/staff-docs/{procedures/rt => rt/rt-guide}/basic-domain-request-template.md (100%) rename docs/staff-docs/{procedures/rt => rt/rt-guide}/i-need-something-with-berkeleyedu.md (100%) rename docs/staff-docs/{procedures/rt => rt/rt-guide}/index.md (100%) rename docs/staff-docs/{procedures/rt => rt/rt-guide}/virtual-hosting-request.md (100%) diff --git a/docs/staff-docs/procedures/accounts/alumni-reset.md b/docs/staff-docs/accounts/alumni-reset.md similarity index 100% rename from docs/staff-docs/procedures/accounts/alumni-reset.md rename to docs/staff-docs/accounts/alumni-reset.md diff --git a/docs/staff-docs/procedures/accounts/association.md b/docs/staff-docs/accounts/association.md similarity index 100% rename from docs/staff-docs/procedures/accounts/association.md rename to docs/staff-docs/accounts/association.md diff --git a/docs/staff-docs/procedures/accounts/class-accounts.md b/docs/staff-docs/accounts/class-accounts.md similarity index 100% rename from docs/staff-docs/procedures/accounts/class-accounts.md rename to docs/staff-docs/accounts/class-accounts.md diff --git a/docs/staff-docs/procedures/accounts/group-accounts.md b/docs/staff-docs/accounts/group-accounts.md similarity index 87% rename from docs/staff-docs/procedures/accounts/group-accounts.md rename to docs/staff-docs/accounts/group-accounts.md index 0840029..e8c4175 100644 --- a/docs/staff-docs/procedures/accounts/group-accounts.md +++ b/docs/staff-docs/accounts/group-accounts.md @@ -1,7 +1,6 @@ -# Group Accounts - -## Change group account password - +--- +title: Group Accounts +--- 1. Have RSO's signatory come in for staff hours, and verify that person is a signatory. @@ -21,4 +20,4 @@ The bottom of the output should show a list of signatories. You can also check t chpass $GROUP_NAME ``` -They may be afraid that nothing appears as they type. Gently reassure them, noting that they will get to verify their password by typing it a second time. \ No newline at end of file +They may be afraid that nothing appears as they type. Gently reassure them, noting that they will get to verify their password by typing it a second time. diff --git a/docs/staff-docs/procedures/accounts/index.md b/docs/staff-docs/accounts/index.md similarity index 100% rename from docs/staff-docs/procedures/accounts/index.md rename to docs/staff-docs/accounts/index.md diff --git a/docs/staff-docs/procedures/accounts/renaming.md b/docs/staff-docs/accounts/renaming.md similarity index 100% rename from docs/staff-docs/procedures/accounts/renaming.md rename to docs/staff-docs/accounts/renaming.md diff --git a/docs/staff-docs/procedures/staff-vms.md b/docs/staff-docs/archive/debian-staff-vms.md similarity index 100% rename from docs/staff-docs/procedures/staff-vms.md rename to docs/staff-docs/archive/debian-staff-vms.md diff --git a/docs/staff-docs/procedures/dmca.md b/docs/staff-docs/dmca.md similarity index 100% rename from docs/staff-docs/procedures/dmca.md rename to docs/staff-docs/dmca.md diff --git a/docs/staff-docs/editing-docs/.nav.yml b/docs/staff-docs/editing-docs/.nav.yml new file mode 100644 index 0000000..ac109cc --- /dev/null +++ b/docs/staff-docs/editing-docs/.nav.yml @@ -0,0 +1 @@ +title: Editing Docs diff --git a/docs/staff-docs/procedures/bod-notes.md b/docs/staff-docs/editing-docs/bod-notes.md similarity index 100% rename from docs/staff-docs/procedures/bod-notes.md rename to docs/staff-docs/editing-docs/bod-notes.md diff --git a/docs/staff-docs/procedures/editing-docs.md b/docs/staff-docs/editing-docs/index.md similarity index 100% rename from docs/staff-docs/procedures/editing-docs.md rename to docs/staff-docs/editing-docs/index.md diff --git a/docs/staff-docs/procedures/gapps.md b/docs/staff-docs/gapps.md similarity index 100% rename from docs/staff-docs/procedures/gapps.md rename to docs/staff-docs/gapps.md diff --git a/docs/staff-docs/get-involved/staff-privileges/.nav.yml b/docs/staff-docs/get-involved/staff-privileges/.nav.yml new file mode 100644 index 0000000..cb56668 --- /dev/null +++ b/docs/staff-docs/get-involved/staff-privileges/.nav.yml @@ -0,0 +1 @@ +title: Staff Privileges diff --git a/docs/staff-docs/procedures/granting-privileges.md b/docs/staff-docs/get-involved/staff-privileges/granting-privileges.md similarity index 100% rename from docs/staff-docs/procedures/granting-privileges.md rename to docs/staff-docs/get-involved/staff-privileges/granting-privileges.md diff --git a/docs/staff-docs/get-involved/staff-privileges.md b/docs/staff-docs/get-involved/staff-privileges/index.md similarity index 100% rename from docs/staff-docs/get-involved/staff-privileges.md rename to docs/staff-docs/get-involved/staff-privileges/index.md diff --git a/docs/staff-docs/procedures/installing-updates.md b/docs/staff-docs/infrastructure/debian-hosts/installing-updates.md similarity index 100% rename from docs/staff-docs/procedures/installing-updates.md rename to docs/staff-docs/infrastructure/debian-hosts/installing-updates.md diff --git a/docs/staff-docs/procedures/live-resize.md b/docs/staff-docs/infrastructure/debian-hosts/live-resize.md similarity index 100% rename from docs/staff-docs/procedures/live-resize.md rename to docs/staff-docs/infrastructure/debian-hosts/live-resize.md diff --git a/docs/staff-docs/procedures/restarting-services.md b/docs/staff-docs/infrastructure/debian-hosts/restarting-services.md similarity index 100% rename from docs/staff-docs/procedures/restarting-services.md rename to docs/staff-docs/infrastructure/debian-hosts/restarting-services.md diff --git a/docs/staff-docs/procedures/setting-up-lacp.md b/docs/staff-docs/infrastructure/debian-hosts/setting-up-lacp.md similarity index 100% rename from docs/staff-docs/procedures/setting-up-lacp.md rename to docs/staff-docs/infrastructure/debian-hosts/setting-up-lacp.md diff --git a/docs/staff-docs/procedures/setting-up-mdraid.md b/docs/staff-docs/infrastructure/debian-hosts/setting-up-mdraid.md similarity index 100% rename from docs/staff-docs/procedures/setting-up-mdraid.md rename to docs/staff-docs/infrastructure/debian-hosts/setting-up-mdraid.md diff --git a/docs/staff-docs/infrastructure/decal/index.md b/docs/staff-docs/infrastructure/decal/index.md new file mode 100644 index 0000000..4925aed --- /dev/null +++ b/docs/staff-docs/infrastructure/decal/index.md @@ -0,0 +1,7 @@ +--- +title: Decal +--- + +The current decal website is hosted on `amethyst` (NixOS VM) and is written in hugo. The code is available at [https://github.com/ocf/hugo-decal-web]. + +Decal laptops are in the storage room. These can be used in place of VMs for a more hands-on linux learning experience. diff --git a/docs/staff-docs/procedures/new-asuc-subdomain.md b/docs/staff-docs/infrastructure/dns/new-asuc-subdomain.md similarity index 100% rename from docs/staff-docs/procedures/new-asuc-subdomain.md rename to docs/staff-docs/infrastructure/dns/new-asuc-subdomain.md diff --git a/docs/staff-docs/procedures/ssl.md b/docs/staff-docs/infrastructure/dns/ssl.md similarity index 100% rename from docs/staff-docs/procedures/ssl.md rename to docs/staff-docs/infrastructure/dns/ssl.md diff --git a/docs/staff-docs/procedures/updating-dns-records.md b/docs/staff-docs/infrastructure/dns/updating-dns-records.md similarity index 100% rename from docs/staff-docs/procedures/updating-dns-records.md rename to docs/staff-docs/infrastructure/dns/updating-dns-records.md diff --git a/docs/staff-docs/infrastructure/hpc/.nav.yml b/docs/staff-docs/infrastructure/hpc/.nav.yml new file mode 100644 index 0000000..c59f5c1 --- /dev/null +++ b/docs/staff-docs/infrastructure/hpc/.nav.yml @@ -0,0 +1 @@ +title: HPC diff --git a/docs/staff-docs/procedures/hpc.md b/docs/staff-docs/infrastructure/hpc/add-hpc-users.md similarity index 100% rename from docs/staff-docs/procedures/hpc.md rename to docs/staff-docs/infrastructure/hpc/add-hpc-users.md diff --git a/docs/staff-docs/procedures/opstaff-email.md b/docs/staff-docs/infrastructure/mail/opstaff-email.md similarity index 100% rename from docs/staff-docs/procedures/opstaff-email.md rename to docs/staff-docs/infrastructure/mail/opstaff-email.md diff --git a/docs/staff-docs/infrastructure/nfs/.nav.yml b/docs/staff-docs/infrastructure/nfs/.nav.yml new file mode 100644 index 0000000..c2d19f2 --- /dev/null +++ b/docs/staff-docs/infrastructure/nfs/.nav.yml @@ -0,0 +1 @@ +title: NFS diff --git a/docs/staff-docs/procedures/user-quotas.md b/docs/staff-docs/infrastructure/nfs/user-quotas.md similarity index 100% rename from docs/staff-docs/procedures/user-quotas.md rename to docs/staff-docs/infrastructure/nfs/user-quotas.md diff --git a/docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/.nav.yml b/docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/.nav.yml new file mode 100644 index 0000000..29ec782 --- /dev/null +++ b/docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/.nav.yml @@ -0,0 +1 @@ +title: Creating Nix Hosts diff --git a/docs/staff-docs/infrastructure/nix-hosts/desktop-bootstrap-instructions.md b/docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/desktop-bootstrap-instructions.md similarity index 100% rename from docs/staff-docs/infrastructure/nix-hosts/desktop-bootstrap-instructions.md rename to docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/desktop-bootstrap-instructions.md diff --git a/docs/staff-docs/infrastructure/nix-hosts/new-hosts.md b/docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/index.md similarity index 99% rename from docs/staff-docs/infrastructure/nix-hosts/new-hosts.md rename to docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/index.md index fcc1130..2a3fa9d 100644 --- a/docs/staff-docs/infrastructure/nix-hosts/new-hosts.md +++ b/docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/index.md @@ -1,5 +1,5 @@ --- -title: Creating New Nix Hosts +title: Creating Nix Hosts --- ## Overview diff --git a/docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/staff-vm.md b/docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/staff-vm.md new file mode 100644 index 0000000..4c56d1b --- /dev/null +++ b/docs/staff-docs/infrastructure/nix-hosts/creating-nix-hosts/staff-vm.md @@ -0,0 +1,13 @@ +--- +title: Staff VMs +--- + +just like look at other staff VMs on `doorplug` (the proxmox node), look at the general guide for creating nix hosts, vibe it out + +## Troubleshooting + +When trying to provision a NixOS VM through ISO (after step 3.), we ran into an issue where no bootable option or device was found. The way to solve this was to attach the ISO first: + +sudo virsh attach-disk [domain name] /var/lib/libvirt/images/latest-nixos-minimal-x86_64-linux.iso sda --driver qemu --type cdrom + +Then disable secure boot in BIOs and add "console=ttys0" to the bootloader screen by pressing "e" and appending the parameter. diff --git a/docs/staff-docs/infrastructure/nix-hosts/index.md b/docs/staff-docs/infrastructure/nix-hosts/index.md index b09f30b..61cfaf7 100644 --- a/docs/staff-docs/infrastructure/nix-hosts/index.md +++ b/docs/staff-docs/infrastructure/nix-hosts/index.md @@ -1,9 +1,7 @@ --- -title: NixOS (Linux Systems) +title: Nix Hosts --- -# NixOS (Linux Systems) - [NixOS](https://nixos.org) is the Linux distribution created from the [nixpkgs](https://github.com/NixOS/nixpkgs) package repository, which is written in the [Nix](https://nixos.wiki/wiki/Overview_of_the_Nix_Language) language. Although our services are based on Kubernetes, there still needs to be some component actually installing packages on servers, and NixOS fulfills this role. For a good introduction on NixOS and Nix, see the excellent third-party documentation available at . @@ -25,6 +23,14 @@ Normally, when you're running an Operating System, say, Windows (eww), you have NixOS is built for 1 core function: ***reproducibility****.* A certain config file will build NixOS a certain way, and that assurance is why we use NixOS. +## Development + +You might want to use Nix on your computer to easily get a development environment for various OCF systems. If the repository has a file called flake.nix in it, you can get a development environment for it as simply as nix shell github.com:ocf/. For example, to get transpire, you can do nix shell github.com:ocf/transpire. + +`nix shell` is really cool because you can use it install and work with any packages you want in a new shell. You can use `nix shell -p pkg1 pkg2` to open a new shell with those packages installed. + +To install Nix, follow the instructions at https://zero-to-nix.com/start/install + ## Old Linux Systems (Puppet) We used to use [Puppet](/doc/puppet-4chWqU6Eqx). Actually we still do use puppet, and most of our legacy infrastructure is on it. See the link in the first sentence for more information! diff --git a/docs/staff-docs/infrastructure/nix-hosts/nix-on-your-computer.md b/docs/staff-docs/infrastructure/nix-hosts/nix-on-your-computer.md deleted file mode 100644 index 44a9edb..0000000 --- a/docs/staff-docs/infrastructure/nix-hosts/nix-on-your-computer.md +++ /dev/null @@ -1,12 +0,0 @@ -# Nix on your Computer - -You might want to use Nix on your computer to easily get a development environment for various OCF systems. If the repository has a file called `flake.nix` in it, you can get a development environment for it as simply as `nix shell github.com:ocf/`. For example, to get [transpire](/doc/configuration-transpire-uJ5GHrW9cg), you can do `nix shell github.com:ocf/transpire`. - - - -:::info -`nix shell` is really cool because you can use it install and work with any packages you want in a new shell. You can use `nix shell -p pkg1 pkg2` to open a new shell with those packages installed. - -::: - -To install Nix, follow the instructions at \ No newline at end of file diff --git a/docs/staff-docs/infrastructure/nix-hosts/how-to-learn-nix.md b/docs/staff-docs/infrastructure/nix-hosts/njha-nix-guide.md similarity index 98% rename from docs/staff-docs/infrastructure/nix-hosts/how-to-learn-nix.md rename to docs/staff-docs/infrastructure/nix-hosts/njha-nix-guide.md index 468ade7..73c1e61 100644 --- a/docs/staff-docs/infrastructure/nix-hosts/how-to-learn-nix.md +++ b/docs/staff-docs/infrastructure/nix-hosts/njha-nix-guide.md @@ -1,4 +1,6 @@ -# How to Learn Nix +--- +title: njha's Guide to Learning Nix +--- This document contains many of the resources that `~njha` used to learn Nix and NixOS. diff --git a/docs/staff-docs/infrastructure/printing/index.md b/docs/staff-docs/infrastructure/printing/index.md new file mode 100644 index 0000000..2e812cb --- /dev/null +++ b/docs/staff-docs/infrastructure/printing/index.md @@ -0,0 +1,5 @@ +--- +title: Printing +--- + +uhhhhh, how do i print here? diff --git a/docs/staff-docs/procedures/printing.md b/docs/staff-docs/infrastructure/printing/maintenance.md similarity index 100% rename from docs/staff-docs/procedures/printing.md rename to docs/staff-docs/infrastructure/printing/maintenance.md diff --git a/docs/staff-docs/infrastructure/printhost.md b/docs/staff-docs/infrastructure/printing/printhost.md similarity index 100% rename from docs/staff-docs/infrastructure/printhost.md rename to docs/staff-docs/infrastructure/printing/printhost.md diff --git a/docs/staff-docs/procedures/process-accounting.md b/docs/staff-docs/infrastructure/process-accounting.md similarity index 100% rename from docs/staff-docs/procedures/process-accounting.md rename to docs/staff-docs/infrastructure/process-accounting.md diff --git a/docs/staff-docs/procedures/fix-compromised-wordpress.md b/docs/staff-docs/infrastructure/web-hosting/fix-compromised-wordpress.md similarity index 100% rename from docs/staff-docs/procedures/fix-compromised-wordpress.md rename to docs/staff-docs/infrastructure/web-hosting/fix-compromised-wordpress.md diff --git a/docs/staff-docs/infrastructure/web-hosting/index.md b/docs/staff-docs/infrastructure/web-hosting/index.md new file mode 100644 index 0000000..29fc0f5 --- /dev/null +++ b/docs/staff-docs/infrastructure/web-hosting/index.md @@ -0,0 +1,7 @@ +--- +title: Web Hosting +--- + +Currently, we host `bestdocs.ocf.io` and `decal.ocf.io` on `amethyst`, a NixOS host for static websites. See the OCF's [nix webhost module](https://github.com/ocf/nix/blob/main/modules/webhost.nix) for more information on its setup, as well as [`amethyst`'s host file](https://github.com/ocf/nix/blob/main/hosts/servers/amethyst.nix) + +`vampires` is for dynamic websites, and `death` is for static web hosting. Both of these are debian hosts. `death` also hosts Wordpress websites for some reason. diff --git a/docs/staff-docs/procedures/.nav.yml b/docs/staff-docs/procedures/.nav.yml deleted file mode 100644 index 6840763..0000000 --- a/docs/staff-docs/procedures/.nav.yml +++ /dev/null @@ -1,3 +0,0 @@ -nav: - - OCF Accounts: accounts - - "*" diff --git a/docs/staff-docs/procedures/handoff.md b/docs/staff-docs/procedures/handoff.md deleted file mode 100644 index f20c05b..0000000 --- a/docs/staff-docs/procedures/handoff.md +++ /dev/null @@ -1,43 +0,0 @@ -# !!! SM/Root Handoff Guide !!! - -## These steps must be followed when on-boarding/off-boarding rootstaff or SMs, or I will be disappointed in you. - - -### On-boarding/off-boarding rootstaff - -The following privileges/accounts must be granted when someone is made root, **and taken away/disabled when they are no longer root**. - -* /root and /admin Kerberos principals -* Membership of the ocfroot LDAP group - - `kinit you/admin` - - `ldapvi cn=ocfroot` -* Kerberos permissions in the ACL list - - `add otherstaffer/admin` - - `add otherstaffer/root` -* 24/7 Keycard Access, and their name on the Emergency after hours list -* Membership of the root@ Google group to receive technical spam -* Membership of the workspace-admins@ Google group to enforce physical security token 2fa -* Super Admin status in Google Workspace -* "Root" role in the OCF Discord -* Owner status in the OCF Github -* A 1password account, membership of the "Owners" group, and access to the root (and really-root?) vaults -* Their hardware token ssh key added to agenix in the ocf/nix repo -* Their ssh key added to nix deploy users -* Membership of the security contact in socreg -* Panorama access (perhaps this should be SM only?) -* //TODO anything I missed? - - -### SM Handoff - -The following steps must be taken every time there is a new Site Manager, to ensure proper transfer of accounts. - -* All of the above steps if one SM is gaining or losing root. -* The following should always be held by one of the current SMs, and such should be transferred to an incoming SM if the person who holds it is leaving: - * Ownership of the OCF Discord - * //TODO i probably forgot a lot of things - * Any account that requires a single user to be the owner -* Additionally, the incoming/outgoing SMs should perform an audit of this list, and ensure that any new/removed manually assigned privileges are reflected here. - -meow -meow (with Brazilian characteristics) diff --git a/docs/staff-docs/procedures/how-to-request-a-purchase.md b/docs/staff-docs/procedures/how-to-request-a-purchase.md deleted file mode 100644 index 3a12a52..0000000 --- a/docs/staff-docs/procedures/how-to-request-a-purchase.md +++ /dev/null @@ -1,24 +0,0 @@ -# How to Request a Purchase - -:::warning -Only Purchase Requests of **less than** $400 will go through this process. - -Purchase Requests of **more than** $400 will need to be approved by the Board of Directors to be purchased. - -::: - - -1. Fill out the form at [ocf.io/buy](https://ocf.io/buy) **BEFORE FRIDAY AT 3:00PM** if you want the purchase to be made the following week - - - 1. Requests made **AFTER FRIDAY AT 3:00PM** will be purchased the week after the following -2. A Ficomm Head will send an email if your request has been approved or denied - - \ - -## If Your Purchase Request Has Been Denied - - -1. Email a Ficomm Head to try and appeal the decision -2. If you are still denied, appeal to the Board of Directors -3. If you are still denied, then the Purchase Request will stay denied \ No newline at end of file diff --git a/docs/staff-docs/procedures/index.md b/docs/staff-docs/procedures/index.md deleted file mode 100644 index b4662b8..0000000 --- a/docs/staff-docs/procedures/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Procedures ---- - -Create pages under this directory to document how to perform common procedures. diff --git a/docs/staff-docs/procedures/sufmo-access.md b/docs/staff-docs/procedures/sufmo-access.md deleted file mode 100644 index 2f1b2b7..0000000 --- a/docs/staff-docs/procedures/sufmo-access.md +++ /dev/null @@ -1,15 +0,0 @@ -# Afterhour Access -## MOU with SUFMO: -https://drive.google.com/drive/search?q=OCF%20SUFMO%20access - -## Adding user to access list -PLEASE READ MOU for updated instructions on how to make changes. - -The access list is at: https://docs.google.com/spreadsheets/d/1h1sumblh7tsxqhoZP1lxi-p-7HGpSJjJnC-A4ZbXm3M/edit?gid=214657590#gid=214657590 - -## Keycard Access -- Add user to OCF Keycard roster: https://docs.google.com/spreadsheets/d/12kwr-CdhHpV1VzznSNfGx0FaOA8T3YUH0c8jqwftBRs/edit?gid=0#gid=0 - - MLK OCF Limited is for access to OCF & OCF Storage Room - - MLK OCF is MLK OCF Limited + Access to side-doors and server rooms -- Fill out keycard access form: https://berkeleysa.tfaforms.net/28?tfa_12=Access%20Request -- Email OCF advisor (Lauren Beal, as of Spring 2026) diff --git a/docs/staff-docs/procedures/volunteer-staff-hours-faq.md b/docs/staff-docs/procedures/volunteer-staff-hours-faq.md deleted file mode 100644 index 026aa43..0000000 --- a/docs/staff-docs/procedures/volunteer-staff-hours-faq.md +++ /dev/null @@ -1,25 +0,0 @@ -# Volunteer Staff Hours FAQ - -## The paper drawer on the printer won't shut! - -Pull out the drawer entirely, off of the little rails (you may need to lift it a bit). Check behind the drawer for paper that may have gotten stuck there. - -# Common Questions - -## Where can I get a website made? - -Although the OCF only offers web hosting, student group representatives may come in looking for front-end web development. There are a few organizations on-campus you can redirect them to: - -* Innovative Design - * - * ASUC-chartered organization - * Their offices are in (placeholder but somewhere in MLK) - * also does design and photography services - * free for berkeley clubs!!! -* Web Development @ Berkeley (WDB) - * - * ==Client contact form is closed as of 4/27/2023== - -## Tips - -It can be beneficial to sit near the opstaff desk so when people ask them for help, you can step in and opstaff can continue checking cards. \ No newline at end of file diff --git a/docs/staff-docs/procedures/rt/basic-domain-request-template.md b/docs/staff-docs/rt/rt-guide/basic-domain-request-template.md similarity index 100% rename from docs/staff-docs/procedures/rt/basic-domain-request-template.md rename to docs/staff-docs/rt/rt-guide/basic-domain-request-template.md diff --git a/docs/staff-docs/procedures/rt/i-need-something-with-berkeleyedu.md b/docs/staff-docs/rt/rt-guide/i-need-something-with-berkeleyedu.md similarity index 100% rename from docs/staff-docs/procedures/rt/i-need-something-with-berkeleyedu.md rename to docs/staff-docs/rt/rt-guide/i-need-something-with-berkeleyedu.md diff --git a/docs/staff-docs/procedures/rt/index.md b/docs/staff-docs/rt/rt-guide/index.md similarity index 100% rename from docs/staff-docs/procedures/rt/index.md rename to docs/staff-docs/rt/rt-guide/index.md diff --git a/docs/staff-docs/procedures/rt/virtual-hosting-request.md b/docs/staff-docs/rt/rt-guide/virtual-hosting-request.md similarity index 100% rename from docs/staff-docs/procedures/rt/virtual-hosting-request.md rename to docs/staff-docs/rt/rt-guide/virtual-hosting-request.md