@@ -13,7 +13,9 @@ Obelisk provides an easy way to develop and deploy your [Reflex](https://github.
1313 - [Running over https](#running-over-https)
1414- [Deploying](#deploying)
1515 - [Locally](#locally)
16− - [EC2](#ec2)
16+ - [Default EC2 Deployment](#default-ec2-deployment)
17+ - [Custom Non-EC2 Deployment](#custom-non-ec2-deployment)
18+ - [VirtualBox Deployment](#virtualbox-deployment)
1719 - [From macOS](#from-macos)
1820 - [Deploying an updated version](#deploying-an-updated-version)
1921- [Mobile](#mobile)
@@ -55,18 +57,18 @@ Obelisk provides an easy way to develop and deploy your [Reflex](https://github.
5557
5658When developing on obelisk itself you may launch `ghcid` for the corresponding project as follows. For example to launch ghcid for `lib/backend` project:
5759
58−```
60+```shell
5961nix-shell -A obeliskEnvs.obelisk-backend --run "cd lib/backend && ghcid -c 'cabal new-repl'"
6062```
6163
6264Or to launch ghcid for `lib/command` project:
6365
64−```
66+```shell
6567nix-shell -A obeliskEnvs.obelisk-command --run "cd lib/command && ghcid -c 'cabal new-repl'"
6668```
6769
6870To re-install `ob` from source do
69−```
71+```shell
7072nix-env -f /path/to/obelisk -iA command
7173```
7274
@@ -100,13 +102,13 @@ access to:
100102
101103To create a new Obelisk project, go to an empty directory and run:
102104
103−```
105+```shell
104106ob init
105107```
106108
107109Obelisk leverages ghcid to provide a live-reloading server that handles both frontend and backend. To run your Obelisk app and monitor the source for changes:
108110
109−```
111+```shell
110112ob run
111113```
112114
@@ -165,7 +167,7 @@ project ./. ({ pkgs, ... }: {
165167# ...
166168```
167169
168−### Running over https
170+### Running over HTTPS
169171
170172To run your app locally over https, update the protocol in `config/common/route` to `https`, and then use `ob run` as normal.
171173
@@ -177,22 +179,22 @@ Since Obelisk generates a self-signed certificate for running https, the browser
177179
178180Build everything:
179181
180−```
182+```shell
181183nix-build -A exe --no-out-link
182184```
183185
184186Copy the result to a new directory, add configuration, and run!
185187
186−```
188+```shell
187189mkdir test-app
188190ln -s $(nix-build -A exe --no-out-link)/* test-app/
189191cp -r config test-app
190192(cd test-app && ./backend)
191193```
192194
193−### EC2
195+### Default EC2 Deployment
194196
195−In this section we will demonstrate how to deploy your Obelisk app to an Amazon EC2 instance.
197+In this section we will demonstrate how to deploy your Obelisk app to an Amazon EC2 instance. Obelisk deployments are configured for EC2 by default (see [Custom Non-EC2 Deployment](#custom-non-ec2-deployment)).
196198
197199First create a new EC2 instance:
198200
@@ -219,7 +221,7 @@ ob deploy init \
219221 ~/code/myapp-deploy
220222```
221223
222−HTTPS is enabled by default; to disable https, pass `--disable-https` to the `ob deploy init` command above.
224+HTTPS is enabled by default; to disable HTTPS pass `--disable-https` to the `ob deploy init` command above.
223225
224226This step will also require that you manually verify the authenticity of the host `$SERVER`. Obelisk will save the fingerprint in a deployment-specific configuration. **Obelisk deployments do *not* rely on the `known_hosts` of your local machine.** This is because, in the event that you need to switch from one deploy machine / bastion host to another, you want to be absolutely sure that you're still connecting to the machines you think you are, even if that deploy machine / bastion host has never connected to them before. Obelisk explicitly avoids a workflow that encourages people to accept host keys without checking them, since that could result in leaking production secrets to anyone who manages to MITM you, e.g. via DNS spoofing or cache poisoning. (Note that an active attack is a circumstance where you may need to quickly switch bastion hosts, e.g. because the attacker has taken one down or you have taken it down in case it was compromised. In this circumstance you might need to deploy to production to fix an exploit or rotate keys, etc.) When you run `ob deploy` later it will rely on the saved verification in this step.
225227
@@ -234,6 +236,26 @@ ob deploy push
234236
235237At this point you are done. Your app will be accessible at `${ROUTE}`. The currently deployed version - the git commit hash of the source repo - can be found at `${ROUTE}/version`.
236238
239+### Custom Non-EC2 Deployment
240+
241+By default Obelisk deployments are configured for NixOS machines running on AWS EC2. To provide your own configuration, you need to write a custom `module.nix` in the deployment repository. This still requires that your server is running NixOS.
242+
243+`module.nix` must contain a Nix *function* that produces a [NixOS module function](https://nixos.org/nixos/manual/index.html#sec-writing-modules). The top-level function takes deployment configuration as arguments: `hostName`, `adminEmail`, `routeHost`, `enableHttps`, `version`, `exe`, `nixosPkgs`. Most of these are the values you specified during `ob deploy init` and are stored in the deployment repository. `version` is a `git` hash for the app that you're deploying. `exe` is the Linux build of the app (as seen in [Deploying Locally](#locally)). `nixosPkgs` is the package set used to construct the NixOS VM.
244+
245+The [VirtualBox Deployment](#virtualbox-deployment) section provides an example.
246+
247+#### VirtualBox Deployment
248+
249+Here's a `module.nix` that is configured for deployment to a VirtualBox VM (running NixOS):
250+
251+```nix
252+{ nixosPkgs, ... }: {...}: {
253+ imports = [ (nixosPkgs.path + /nixos/modules/virtualisation/virtualbox-image.nix) ];
254+}
255+```
256+
257+The `{...}:` and following is the [NixOS module](https://nixos.org/nixos/manual/index.html#sec-writing-modules) definition.
258+
237259### From macOS
238260
239261Deploying from macOS requires some extra setup:
@@ -247,7 +269,7 @@ Running `ob deploy push` will give you additional setup instructions.
247269
248270If you'd like to deploy an updated version (with new commits) of your Obelisk app: simply go to the configuration directory, update the source thunk and push:
249271
250−```
272+```shell
251273cd ~/code/myapp-deploy
252274ob deploy update
253275ob deploy push
@@ -273,14 +295,14 @@ These versions will work out of the box but iOS SDKs prior to 11.3 should also w
273295
274296More recent Xcodes should also work, as long as one of the SDKs mentioned above has been used.
275297To add another SDK to your current Xcode, [download](https://developer.apple.com/download/more/) the corresponding Xcode, extract it and copy its SDK folder next to the installed one, e.g.
276−```
298+```shell
277299open -W Xcode_9.2.xip
278300sudo cp -R Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS11.2.sdk
279301```
280302
281303
282304You can verify that you have correct versions by running
283−```
305+```shell
284306xcodebuild -showsdks
285307```
286308
@@ -306,7 +328,7 @@ Ensure that `bundleIdentifier` matches the App ID of the development profile, or
3063281. Connect the registered iPhone.
3073291. Find your Apple Team ID in the [developer portal](https://developer.apple.com/account/#/membership).
3083301. Run the deploy command with your Team ID:
309−```
331+```shell
310332result-ios/bin/deploy [TEAM_ID]
311333# or in debug mode via lldb:
312334result-ios/bin/deploy [TEAM_ID] -d
@@ -316,7 +338,7 @@ result-ios/bin/deploy [TEAM_ID] -d
3163381. Go to [developer portal - distribution profiles](https://developer.apple.com/account/ios/profile/production).
317339Create and download a distribution profile.
3183401. Run the package script with your TEAM ID and your distribution profile to create a `.ipa`:
319−```
341+```shell
320342result-ios/bin/package [TEAM_ID] /path/to/output/.ipa /path/to/profile/file
321343```
322344