@@ -1,11 +1,12 @@
11# Obelisk Application Deployment Guide
2+
23This document serves two purposes, the first one is to guide new users that want to deploy Obelisk/Reflex apps and the second one to provide a walk-through for test driving Obelisk releases.
34
4−> **Note:** To complete this *entire* guide you need access to a macOS machine running the latest OSX release, a Linux machine (can be a VM on that mac) with Nix installed, an iPhone or iPad, and a recent Android device. It also assumes that you have Nix correctly set up and that your system is set up to fetch from binary caches instead of building everything on your machine. If you notice any of the commands below takes more than 5 minutes, then caches are not likely enabled.
5+> **Note:** This guide can be completed on a Linux host with Nix installed or a macOS host with Nix installed. Each section is labeled regarding which operating system hosts it supports. When going through the guide, start at the beginning and go through all sections that are supported on your host and merely skip sections that are not supported. The sections for iOS deployments require an iPhone or iPad device and the sections for Android deployments require an Android device. This guide assumes that you have Nix correctly set up and that your system is configured to fetch from binary caches instead of building everything on your machine. If you notice any of the commands below takes more than 5 minutes, then caches are not likely enabled.
56>
67> Refer to the [Obelisk Installation Documentation](https://github.com/obsidiansystems/obelisk#installing-obelisk) for instructions on configuring the binary caches for any Nix-compatible setup.
78
8−## a) Get Obelisk
9+## a) Get Obelisk (Linux, Mac)
910
1011There are several ways to install Obelisk, but the one we are going to use here allows us to test a single version of Obelisk in different ways. The approach is to clone Obelisk from it's GitHub repository and start a project that uses that local check out.
1112
@@ -39,7 +40,7 @@ ob init --branch "$OBELISK_BRANCH"
3940
4041> **Note:** If the `--branch` parameter is not used, then Obelisk sets your project up to look at the `master` branch from GitHub. This is quite handy for real life projects but distracting for our test drive since we want to make sure any changes we do to the Obelisk codebase (like testing a pull request) are immediately picked up.
4142
42−## b) Run the Obelisk app on localhost
43+## b) Run the Obelisk app on localhost (Linux, Mac)
4344
4445Let's test that we can run a server on localhost. This is quite easy:
4546
@@ -52,9 +53,10 @@ Now open a browser and point it to http://localhost:8000 (or just click on this
5253
5354
5455
55−## c) Deploy the web app on a remote machine
56+## c) Prepare a VirtualBox deploy target (Linux, Mac)
5657
5758### Import the NixOS VirtualBox appliance
59+
5860Install [VirtualBox](https://www.virtualbox.org/) on your machine.
5961
6062On NixOS, do this by adding the following line to your `/etc/nixos/configuration.nix` before the last line containing `}`:
@@ -201,7 +203,7 @@ git remote add origin "$WORKDIR/myapp-git-remote"
201203git push -u origin master
202204```
203205
204−### Deploy
206+### Initialize deployment directory
205207
206208With that, we can come back to the Obelisk app and initialize the deployment:
207209
@@ -216,7 +218,11 @@ Then configure the deployment for VirtualBox:
216218echo '{nixosPkgs, ...}: {...}: { imports = [ (nixosPkgs.path + /nixos/modules/virtualisation/virtualbox-image.nix) ]; }' > "$WORKDIR/myappdeploy/module.nix"
217219```
218220
219−And deploy:
221+## d) Deploy to VirtualBox target (Linux only)
222+
223+> Deploying requires a Linux host in order to build the Linux binaries.
224+
225+Now we can deploy to the VirtualBox VM.
220226
221227```bash
222228cd "$WORKDIR/myappdeploy"
@@ -243,7 +249,7 @@ It should look like this:
243249
244250Congratulations! You have deployed an Obelisk application to a remote server via SSH.
245251
246−## d) Deploy an Android app (Linux host only)
252+## e) Deploy an Android app (Linux only)
247253
248254> **Note:** This section requires that you be running a Linux *host*.
249255
@@ -286,7 +292,7 @@ When the deployment is complete opening the app should look something like
286292
287293Congratulations! You have deployed an Obelisk Android app via USB.
288294
289−## e) Deploy an iOS app (macOS host only)
295+## f) Deploy an iOS app (Mac only)
290296
291297> **Note:** This section requires that you be running a macOS *host*.
292298