3 files changed, 140 insertions, 0 deletions
diff --git a/Documentation/installation/binary-cache.adoc b/Documentation/installation/binary-cache.adoc
new file mode 100644
index 0000000..ab53666
--- /dev/null
+++ b/Documentation/installation/binary-cache.adoc
@@ -0,0 +1,63 @@
+= Setting Up Binary Cache
+:page-parent: Build and Run
+:page-nav_order: 1
+
+// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Building Spectrum from source can take a very long time.  To avoid
+having to wait when building the system to try it out or test patches,
+an x86_64 binary cache service is available.  If configured to do so,
+Nix will download build outputs from the cache, instead of building
+them locally.
+
+Builds are run on the latest NixOS unstable on
+https://www.vultr.com/[Vultr], and are signed to ensure authenticity.
+The build infrastructure and signing key are accessible by Alyssa Ross
+and Puck Meerburg.  Storage is provided by Daniel Kuehn.  Please
+https://spectrum-os.org/participating.html[get in touch] if you
+encounter any trouble with it.
+
+The binary cache is currently not able to provide logs, due to a
+https://github.com/NixOS/nix/pull/6051[Nix bug].
+
+== For NixOS
+
+Add the following configuration to /etc/nixos/configuration.nix:
+
+[source,nix]
+----
+{ ... }:
+
+{
+  nix.settings.substituters = [ "https://cache.dataaturservice.se/spectrum/" ];
+  nix.settings.trusted-public-keys = [
+    "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
+    "spectrum-os.org-1:rnnSumz3+Dbs5uewPlwZSTP0k3g/5SRG4hD7Wbr9YuQ="
+  ];
+}
+----
+
+This configuration adds the Spectrum binary cache as a substituter and makes
+Nix trust builds signed with its public key.
+
+To apply changes, rebuild your system with the https://nixos.wiki/wiki/Nixos-rebuild[nixos-rebuild] command.
+
+
+== For Non-NixOS Systems
+
+Add the following configuration to /etc/nix/nix.conf:
+
+[source]
+----
+substituters = https://cache.dataaturservice.se/spectrum/ https://cache.nixos.org/
+trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= spectrum-os.org-1:rnnSumz3+Dbs5uewPlwZSTP0k3g/5SRG4hD7Wbr9YuQ=
+----
+
+Run `systemctl restart nix-daemon.service` after making any changes in the Nix
+configuration.  After that the binary cache will be used automatically when
+`nix-build` is run.
+
+If you have other binary caches configured besides cache.nixos.org,
+make sure to add the Spectrum cache URL and public key to the existing
+configuration lines in your nix.conf file.
diff --git a/Documentation/installation/getting-spectrum.adoc b/Documentation/installation/getting-spectrum.adoc
new file mode 100644
index 0000000..392cab5
--- /dev/null
+++ b/Documentation/installation/getting-spectrum.adoc
@@ -0,0 +1,54 @@
+= Getting Spectrum
+:page-parent: Build and Run
+:page-nav_order: 2
+
+// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+To get Spectrum, you need to build it from source.  As long as you're
+running Linuxfootnote:[Building from other operating systems might
+work, but hasn't been tested.  Patches are welcome to support building
+from other operating systems, as long as they're not too invasive.]
+and have https://nixos.org/download.html[Nix] and https://git-scm.com/[git]
+installed, it's very easy to do.
+
+TIP: Before you start, consider setting up the
+xref:binary-cache.adoc[Spectrum binary cache], which will save you a
+lot of time waiting for builds.
+
+== Trying Spectrum
+
+If you want to try Spectrum out to get a feel for it, without
+installing it, you can run it in a development VM with some example
+applications.
+
+[source,shell]
+----
+git clone https://spectrum-os.org/git/spectrum
+git clone https://github.com/NixOS/nixpkgs
+git clone -b rootfs --reference nixpkgs \
+  https://spectrum-os.org/git/nixpkgs nixpkgs-spectrum
+cd spectrum/host/rootfs
+nix-shell -I nixpkgs=../../../nixpkgs-spectrum --run 'make run'
+----
+
+This builds just enough of Spectrum to try it out in a VM, but it will
+still take a very long time.
+
+== Building Installer
+
+[source,shell]
+----
+git clone https://spectrum-os.org/git/spectrum
+nix-build spectrum/img/combined \
+  -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz
+----
+
+If you haven't set up the xref:binary-cache.adoc[binary cache], this
+will take a very long time.  When it's done, a symbolic link named
+"result" will appear, pointing to a Spectrum USB installer image.
+
+CAUTION: Do not use Spectrum for anything important or sensitive as it is not
+yet suitable for real-world use.  Many important security properties are
+currently missing, and there is no procedure for updating to
+new versions—you have to reinstall the OS.
diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc
new file mode 100644
index 0000000..d67c88d
--- /dev/null
+++ b/Documentation/installation/index.adoc
@@ -0,0 +1,23 @@
+= Build and Run
+:description: How to download and install Spectrum OS.
+:page-nav_order: 2
+:page-has_children: true
+:page-has_toc: false
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+
+To start working with Spectrum, you need:
+
+* xref:../installation/binary-cache.adoc[Set up the binary cache] to speed up the build process.
+* xref:../installation/getting-spectrum.adoc[Build Spectrum] from the source.
+
+TIP: At this stage, Spectrum works only on x86-64.  AArch64 support is in
+development.
+
+== Uninstalling and Updating
+
+Currently, there is no implementation for a software update.
+
+You can replace Spectrum by installing another OS.