1 files changed, 76 insertions, 0 deletions
diff --git a/docs/10-bootstrapping.md b/docs/10-bootstrapping.md
new file mode 100644
index 0000000..05f8867
--- /dev/null
+++ b/docs/10-bootstrapping.md
@@ -0,0 +1,76 @@
+Bootstrapping the Environment
+=============================
+
+Most hosts that are built with `boxconf` depend on at least two other hosts
+being available:
+
+  1. The IDM (identity management) server. This server provides DNS, Kerberos
+     authentication, and LDAP user and group lookups.
+
+  2. The package repository. Almost all hosts are FreeBSD, and they depend on
+     the local `poudriere` server which hosts in-house packages built with
+     custom options.
+
+The IDM servers and the package repo are themselves built with boxconf, but you
+must build them in a specific order to solve the chicken-and-egg problem.
+
+
+## Step 1: The Hypervisor
+
+It is assumed that most hosts will be FreeBSD jails. Therefore, you will need
+a FreeBSD "hypervisor" along with our custom `jailctl` script.
+
+Boxconf can be used to configure a FreeBSD hypervisor for running jails and
+bhyve VMs. The only requirement for this server is a NIC that supports VLAN
+tagging. By default, this interface is assumed to be `lagg0`.
+
+Boxconf assumes any host named `alcatraz[0-9]` has the `freebsd_hypervisor`
+hostclass. Therefore, you can run the following to setup the jail host:
+
+    ./boxconf -s $FREEBSD_HYPERVISOR_IP alcatraz1
+
+Then, on `alcatraz1`, download a FreeBSD rootfs image used for templating jails:
+
+    alcatraz1# jailctl download-release 14.1-RELEASE
+
+
+## Step 2: The Pkg Repository
+
+First, we'll need a jail to serve as our Poudriere server. This jail will build
+all the necessary packages and serve them over HTTP.
+
+On the FreeBSD hypervisor, use `jailctl` to create a jail for the `pkg` repo.
+The following command will create a jail named `pkg1` with VLAN tag `199`,
+IP address `10.11.199.4`, 32G memory limit, 256G disk quota, and 32 CPU cores.
+Note that running `poudriere` in a jail requires many custom jail options, which
+are also set with this command.
+
+    alcatraz1# jailctl create \
+      -v 199 \
+      -a 10.11.199.4 \
+      -k ~/id_ed25519.pub \
+      -c 64-95 \
+      -m 32g \
+      -q 256g \
+      -e mount.procfs=true \
+      -e allow.mount.tmpfs=true \
+      -e allow.mount.devfs=true \
+      -e allow.mount.procfs=true \
+      -e allow.mount.nullfs=true \
+      -e allow.mount.linprocfs=true \
+      -e allow.raw_sockets=true \
+      -e allow.socket_af=true \
+      -e allow.mlock=true \
+      -e sysvmsg=new \
+      -e sysvsem=new \
+      -e sysvshm=new \
+      -e children.max=1000 \
+      pkg1 freebsd14.1
+
+Now you are ready to build all the packages and create the repository. `boxconf`
+assumes that any host named `pkg[0-1]` has the `pkg_repository` hostclass.
+
+    ./boxconf -e idm_bootstrap=true 10.11.199.4
+
+Substitute whatever IP you chose for the `pkg1` jail as necessary. Note that it
+will take a while to build all the packages for the first time.