@@ -1,11 +1,12 @@
1# Obelisk Application Deployment Guide
1# Obelisk Application Deployment Guide
2This 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.
3This 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.
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.
6> 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.
7> 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.
8−## a) Get Obelisk
9+## a) Get Obelisk (Linux, Mac)
10There 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.
11There 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.
@@ -39,7 +40,7 @@ ob init --branch "$OBELISK_BRANCH"
40> **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.
41> **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.
42−## b) Run the Obelisk app on localhost
43+## b) Run the Obelisk app on localhost (Linux, Mac)
44Let's test that we can run a server on localhost. This is quite easy:
45Let's test that we can run a server on localhost. This is quite easy:
@@ -52,9 +53,10 @@ Now open a browser and point it to http://localhost:8000 (or just click on this
53
54
55−## c) Deploy the web app on a remote machine
56+## c) Prepare a VirtualBox deploy target (Linux, Mac)
57### Import the NixOS VirtualBox appliance
58### Import the NixOS VirtualBox appliance
58Install [VirtualBox](https://www.virtualbox.org/) on your machine.
60Install [VirtualBox](https://www.virtualbox.org/) on your machine.
60On NixOS, do this by adding the following line to your `/etc/nixos/configuration.nix` before the last line containing `}`:
62On 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"
201git push -u origin master
203git push -u origin master
204−### Deploy
206+### Initialize deployment directory
206With that, we can come back to the Obelisk app and initialize the deployment:
208With that, we can come back to the Obelisk app and initialize the deployment:
@@ -216,7 +218,11 @@ Then configure the deployment for VirtualBox:
216echo '{nixosPkgs, ...}: {...}: { imports = [ (nixosPkgs.path + /nixos/modules/virtualisation/virtualbox-image.nix) ]; }' > "$WORKDIR/myappdeploy/module.nix"
218echo '{nixosPkgs, ...}: {...}: { imports = [ (nixosPkgs.path + /nixos/modules/virtualisation/virtualbox-image.nix) ]; }' > "$WORKDIR/myappdeploy/module.nix"
219−And deploy:
221+## d) Deploy to VirtualBox target (Linux only)
223+> Deploying requires a Linux host in order to build the Linux binaries.
225+Now we can deploy to the VirtualBox VM.
222cd "$WORKDIR/myappdeploy"
228cd "$WORKDIR/myappdeploy"
@@ -243,7 +249,7 @@ It should look like this:
244Congratulations! You have deployed an Obelisk application to a remote server via SSH.
250Congratulations! You have deployed an Obelisk application to a remote server via SSH.
246−## d) Deploy an Android app (Linux host only)
252+## e) Deploy an Android app (Linux only)
248> **Note:** This section requires that you be running a Linux *host*.
254> **Note:** This section requires that you be running a Linux *host*.
@@ -286,7 +292,7 @@ When the deployment is complete opening the app should look something like
287Congratulations! You have deployed an Obelisk Android app via USB.
293Congratulations! You have deployed an Obelisk Android app via USB.
289−## e) Deploy an iOS app (macOS host only)
295+## f) Deploy an iOS app (Mac only)
291> **Note:** This section requires that you be running a macOS *host*.
297> **Note:** This section requires that you be running a macOS *host*.