Skip to content

Latest commit

 

History

History
332 lines (284 loc) · 8.18 KB

README.md

File metadata and controls

332 lines (284 loc) · 8.18 KB

Auron

Auron is the open source codebase automating Haskell.org, built on NixOS and NixOps. We use it to:

  • Manage all of Haskell.org, including users and security updates.
  • Deploy things reproducibly and easily from any Linux box.
  • Send status updates to the status site.
  • Send patches to Phabricator.
  • And more!

Setup

IMPORTANT: You must be using Linux and Nix 1.7 or later for things to work properly! Otherwise ./bin/shell will not start.

  • Clone this repo.
  • Update the submodules - run git submodule init && git submodule update
  • Run ./bin/shell

This will drop you into an instance of nix-shell, with pre-configured NixOps networks for EC2, Rackspace, and VirtualBox. You can run nixops list to see all networks and VMs.

Getting started

Once you've launched ./bin/shell, you can begin deployments. The default nixops network is vbox, which uses the VirtualBox backend for testing.

To get started, deploy a MariaDB and Phabricator pair:

$ nixops deploy --include mysql01 phabricator

NOTE: This generates temporary SSL keys for nginx under /root/ssl.

We also need to generate keys for spiped, so that the Phabricator server can securely communicate with the MariaDB server. This automatically restarts the right systemd units and copies the keys in the right place, so you can run this command over and over to rekey the servers.

$ ./bin/genspiped mysql mysql01 phabricator

Finally, upgrade the database schema, and set the phabricator.base-uri configuration option (so Phabricator knows where to load resources from). This can be done with a one-liner.

NOTE: Set phabricator.base-uri to the FQDN your server will be located at, or set it to the IP address assigned in nixops info. Note the protocol must be https.

$ nixops ssh phabricator -- phab-upgrade --nopass && nixops ssh phabricator -- \
    phab-config set phabricator.base-uri https://<YOUR BASE URI>/

Now, visit the URL you specified for base-uri (either the IP address or FQDN) and register an administration account. Once you're logged in, you'll need to configure mail and authentication providers.

Other providers

The default deployment network is vbox for testing. You can change this for all commands in the shell to ec2 or rackspace by setting the NIXOPS_DEPLOYMENT environment variable before nixops deploy:

$ export NIXOPS_DEPLOYMENT=rackspace
$ export NIXOPS_DEPLOYMENT=ec2

Then use nixops as usual.

NOTE: The rackspace provider does not work and falls back to VirtualBox. See NixOps issue #168.

NOTE: Read the NixOps manual for more information, including how to get EC2 keys set up for testing.

Hacking

If you're going to hack on the source code, here are some notes.

Filesystem layout:

Directory Purpose
`bin/` Scripts for launching the main shell and interacting with machines.
`etc/` 3rd party source code and private data.
`src/` NixOps expressions.
`src/deploy/` Expressions for deployment endpoints (EC2, VBox, or Rackspace).
`src/hosts/` Host descriptions for every major [Haskell.org](https://haskell.org) server.
`src/hosts/roles` Specific roles that a host may take on, including monitoring, services, etc.
`src/modules/` Custom NixOS modules for our servers.
`src/pkgs/` Custom Nix packages for our servers.
`src/res/` Misc. expressions, including user descriptions.
`src/network.nix` Top-level NixOps network description.

Hostname mapping:

The following table maps every //logical hostname// to a //physical hostname//.

Externally, every host is referred to and known solely by the logical hostname (e.g. mysql01, phabricator, wiki). Logical hostnames also correspond to subdomains of haskell.org.

The //physical hostnames// are the actual names of the boxes, as they exist on the machine. So if you access user@mysql01, after logging in the hostname will be vivi. These names are internal, and they are based on the names of Final Fantasy characters.

NOTE: The source code file for every host under src/hosts/ is named after the //physical// hostname, not the logical one! So if you want to improve mysql01, look in src/hosts/vivi.nix.

Logical hostname Physical hostname
[planet](https://planet.haskell.org) Squall
`mysql01` Vivi
[wiki](https://wiki.haskell.org) Yuna
[phabricator](https://phabricator.haskell.org) Rikku
[darcs](https://darcs.haskell.org) Rinoa
[ghc](https://ghc.haskell.org/trac/ghc) Cloud
[www](https://www.haskell.org) Cid
[hackage](https://hackage.haskell.org) Terra
[monitor](https://monitor.haskell.org) Lulu
`hackage-build` Barret
[community](http://community.haskell.org) Freya
`mail` Fran
`try` Kimahri
`phab-ghc01` Wakka

Status:

The following table lists the current status of each machine in terms of parity with the current Haskell.org in features and stability.

Hostname Status
Squall/planet **In-progress**
Vivi/mysql01 **Done** (secured via `spiped`)
Yuna/wiki **In-progress**
Rikku/phabricator **Done**
Rinoa/darcs **Done**
Cloud/ghc **Incomplete**
Cid/www **Incomplete**
Terra/hackage **Incomplete**
Lulu/monitor **Mostly complete** (Nagios, no Datadog stats)
Barret/hackage-build **Incomplete**
Freya/community **Incomplete**
Fran/mail **Incomplete**
Kimahri/try **Incomplete**
Wakka/phab-ghc01 **Incomplete**

Contributing

Patches, comments, and tickets should be submitted through Phabricator, using Maniphest and Arcanist. You'll need to create an account.

If you have a patch, first, drop into ./bin/shell, then commit it and upload with arc diff:

$ ./bin/shell
$ git commit -asm "Fix thing"
$ arc diff

NOTE: Using ./bin/shell is the recommended way to use the arc tool, to ensure it is the same version that Haskell.org uses.

IMPORTANT: Make sure you use -s to add a Signed-off-by line! This specifies you agree the submitted code abides by the project license unless explicitly noted otherwise.

For reviewers, you can specify #auron to add all of the developers.

Read the Arcanist guide for more.

License

Auron is released under the MIT license except as otherwise noted. See LICENSE.txt for details.