Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 0 additions & 1 deletion docs/staff-docs/.nav.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,4 @@ nav:
- Getting Involved: get-involved
- Request Tracker (RT): rt
- "*"
- Staff Virtual Machines: staffvm
- archive
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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.
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.
File renamed without changes.
1 change: 1 addition & 0 deletions docs/staff-docs/editing-docs/.nav.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
title: Editing Docs
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,4 @@ Making a new account requires Google Admin privileges.


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.
4. Add the user to the appropriate Google groups, and (if needed) add them as members on the OCF Staff shared drive.
1 change: 1 addition & 0 deletions docs/staff-docs/get-involved/staff-privileges/.nav.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
title: Staff Privileges
1 change: 1 addition & 0 deletions docs/staff-docs/infrastructure/debian-hosts/.nav.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
title: Debian Hosts
7 changes: 7 additions & 0 deletions docs/staff-docs/infrastructure/debian-hosts/index.md
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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/

7 changes: 7 additions & 0 deletions docs/staff-docs/infrastructure/decal/index.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions docs/staff-docs/infrastructure/dns/.nav.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
title: DNS
5 changes: 5 additions & 0 deletions docs/staff-docs/infrastructure/dns/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
title: DNS
---

How DNS works (and often, does not work) at the OCF
2 changes: 1 addition & 1 deletion docs/staff-docs/infrastructure/external-firewall.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
1 change: 1 addition & 0 deletions docs/staff-docs/infrastructure/hpc/.nav.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
title: HPC
2 changes: 1 addition & 1 deletion docs/staff-docs/infrastructure/mail/vhost.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/).

2 changes: 1 addition & 1 deletion docs/staff-docs/infrastructure/manage-chat.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Managing Chat
title: Managing OCF Chat
---

config on host stored in `/etc/ergo.yaml`. should pull from github
Expand Down
1 change: 1 addition & 0 deletions docs/staff-docs/infrastructure/nfs/.nav.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
title: NFS
1 change: 1 addition & 0 deletions docs/staff-docs/infrastructure/nix-hosts/.nav.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
title: Nix Hosts
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
title: Creating Nix Hosts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Creating New Nix Hosts
title: Creating Nix Hosts
---

## Overview
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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 <https://zero-to-nix.com>.
Expand All @@ -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/<reponame>. 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!
118 changes: 118 additions & 0 deletions docs/staff-docs/infrastructure/nix-hosts/login-servers.md
Original file line number Diff line number Diff line change
@@ -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/`.

Original file line number Diff line number Diff line change
@@ -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.

Expand Down
5 changes: 5 additions & 0 deletions docs/staff-docs/infrastructure/printing/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
title: Printing
---

uhhhhh, how do i print here?
7 changes: 7 additions & 0 deletions docs/staff-docs/infrastructure/web-hosting/index.md
Original file line number Diff line number Diff line change
@@ -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.
37 changes: 0 additions & 37 deletions docs/staff-docs/nix/TODO.md

This file was deleted.

12 changes: 0 additions & 12 deletions docs/staff-docs/nix/ci.md

This file was deleted.

9 changes: 0 additions & 9 deletions docs/staff-docs/nix/modules.md

This file was deleted.

12 changes: 0 additions & 12 deletions docs/staff-docs/nix/nix-on-your-computer.md

This file was deleted.

Loading
Loading