*** Building the installation CD ***

(Or just grab an ISO from http://nix.cs.uu.nl/dist/nix/.)

- Make sure that you have a very recent Nix.

- Pull from the Nixpkgs channel to speed up building.

- Check out https://svn.cs.uu.nl:12443/repos/trace/nixos/trunk/.

- Make a symbolic link called "pkgs" to the location of Nixpkgs.

- Build the ISO image:

  $ nix-build configuration/rescue-cd.nix -A rescueCD

  This gives you an image in result/iso/nixos.iso.

- Burn the ISO image or attach it to a CD-ROM drive in VMware.


*** Installation ***

- Boot from the CD.

- The CD contains a pretty complete NixOS installation.  When it's
  finished booting, it should have detected most of your hardware and
  brought up networking (check ifconfig).  Networking is necessary for
  the installer.  It's best if you have a DHCP server on your
  network.  Otherwise configure manually.

- Login as "root", empty password.

- The NixOS installer doesn't do any partitioning or formatting yet,
  so you need to that yourself.  Use "fdisk", "mkfs.ext2" and "tune2fs".

- Mount the target root device, e.g., under /mnt.

- Unpack the NixOS and Nixpkgs sources:

  $ tar xf /nixos.tar.bz2
  $ tar xf /nixpkgs.tar.bz2
  $ ln -s nixpkgs-*/pkgs .

  (TODO: do this automatically.)

- The installation is declarative; you need to make a description of
  the configuration that is to be built and activated.  The
  configuration is specified in a Nix expression.  See
  configuration/examples for example machine configurations.  You can
  copy and edit one of those (e.g., configuration/examples/basic.nix
  to my-config.nix).  See system/options.nix for available
  configuration settings.  The text editor "nano" is available.

  In particular you need to specify boot.rootDevice and
  boot.grubDevice for the devices where the OS and Grub are to be
  installed, respectively.

- Do the installation:

  $ nixos-installer.sh ROOTDIR . my-config.nix

  where ROOTDIR is the mount point of the target root device (i.e.,
  boot.rootDevice in your configuration).

- If everything went well:

  $ reboot

  You should now be able to boot into the installed NixOS.


*** Updating NixOS ***

- In NixOS, login as root, then do

  $ checkout-nixos.sh  # !!! should be added to the installation

  This gives you a working copy of NixOS and NixPkgs in nixos/ and
  nixpkgs/, respectively.  You only need to do this once; you can use
  "svn up" afterwards.

- The system configuration is in /etc/nixos/configuration.nix.

- To upgrade to a new configuration:

  $ cd nixos
  $ ./upgrade.sh

  The new configuration is activated immediately (e.g., services may
  be restarted if necessary), but some changes may require a reboot.

- You can also test a new configuration:

  $ cd nixos
  $ ./test.sh

  This is like ./upgrade.sh, only the new configuration won't be
  installed in the system profile so the system will continue to boot
  from the previous configuration.



*** Troubleshooting ***        


To get a Stage 1 shell:

- Add "debug1" to the kernel command line.


To switch to maintenance mode:

  $ shutdown now

To get out of maintenance mode:

  $ initctl emit startup 



*** Development ***

- Building specific parts of NixOS:

  $ nix-build system/system.nix \
      --arg configuration "import /etc/nixos/configuration.nix" \
      -A ATTR

  where ATTR is an attribute in system/system.nix (e.g., bootStage1).

- Testing the installer:

  $ dd if=/dev/zero of=diskimage seek=2G count=0 bs=1
  $ yes | mke2fs -j diskimage
  $ mount -o loop diskimage /mnt
  $ nixos-installer /mnt /etc/nixos/nixos/ /etc/nixos/configuration.nix