113ac3f · obelisk · git.iko.soy

git.iko.soy/obelisk

on master help sign in

Document non-EC2 deployment support

113ac3fElliot Cameron7 years ago

ChangeLog.md+1

compare with master

unifiedsplit

@@ -5,6 +5,7 @@ This project's release branch is `master`. This log is written from the perspect

5## Unreleased

7* Fully support HTTP [Range](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range) requests on static assets to support Safari. ([#664](https://github.com/obsidiansystems/obelisk/pull/664))

8+* Support non-EC2 deployments. ([#658](https://github.com/obsidiansystems/obelisk/pull/658))

9## v0.6.0.0 - 2020-02-21

10## v0.6.0.0 - 2020-02-21

README.md+39−17

@@ -13,7 +13,9 @@ Obelisk provides an easy way to develop and deploy your [Reflex](https://github.

13 - [Running over https](#running-over-https)

14- [Deploying](#deploying)

15 - [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)

17 - [From macOS](#from-macos)

19 - [From macOS](#from-macos)

18 - [Deploying an updated version](#deploying-an-updated-version)

20 - [Deploying an updated version](#deploying-an-updated-version)

19- [Mobile](#mobile)

21- [Mobile](#mobile)

@@ -55,18 +57,18 @@ Obelisk provides an easy way to develop and deploy your [Reflex](https://github.

56When developing on obelisk itself you may launch `ghcid` for the corresponding project as follows. For example to launch ghcid for `lib/backend` project:

58When developing on obelisk itself you may launch `ghcid` for the corresponding project as follows. For example to launch ghcid for `lib/backend` project:

58−```

60+```shell

59nix-shell -A obeliskEnvs.obelisk-backend --run "cd lib/backend && ghcid -c 'cabal new-repl'"

61nix-shell -A obeliskEnvs.obelisk-backend --run "cd lib/backend && ghcid -c 'cabal new-repl'"

60```

62```

62Or to launch ghcid for `lib/command` project:

64Or to launch ghcid for `lib/command` project:

64−```

66+```shell

65nix-shell -A obeliskEnvs.obelisk-command --run "cd lib/command && ghcid -c 'cabal new-repl'"

67nix-shell -A obeliskEnvs.obelisk-command --run "cd lib/command && ghcid -c 'cabal new-repl'"

66```

68```

68To re-install `ob` from source do

70To re-install `ob` from source do

69−```

71+```shell

70nix-env -f /path/to/obelisk -iA command

72nix-env -f /path/to/obelisk -iA command

71```

73```

@@ -100,13 +102,13 @@ access to:

100

102

101To create a new Obelisk project, go to an empty directory and run:

103To create a new Obelisk project, go to an empty directory and run:

102

104

103−```

105+```shell

104ob init

106ob init

105```

107```

106

108

107Obelisk 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:

109Obelisk 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:

108

110

109−```

111+```shell

110ob run

112ob run

111```

113```

112

114

@@ -165,7 +167,7 @@ project ./. ({ pkgs, ... }: {

165# ...

167# ...

166```

168```

167

169

168−### Running over https

170+### Running over HTTPS

169

171

170To run your app locally over https, update the protocol in `config/common/route` to `https`, and then use `ob run` as normal.

172To run your app locally over https, update the protocol in `config/common/route` to `https`, and then use `ob run` as normal.

171

173

@@ -177,22 +179,22 @@ Since Obelisk generates a self-signed certificate for running https, the browser

177

179

178Build everything:

180Build everything:

179

181

180−```

182+```shell

181nix-build -A exe --no-out-link

183nix-build -A exe --no-out-link

182```

184```

183

185

184Copy the result to a new directory, add configuration, and run!

186Copy the result to a new directory, add configuration, and run!

185

187

186−```

188+```shell

187mkdir test-app

189mkdir test-app

188ln -s $(nix-build -A exe --no-out-link)/* test-app/

190ln -s $(nix-build -A exe --no-out-link)/* test-app/

189cp -r config test-app

191cp -r config test-app

190(cd test-app && ./backend)

192(cd test-app && ./backend)

191```

193```

192

194

193−### EC2

195+### Default EC2 Deployment

194

196

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)).

196

198

197First create a new EC2 instance:

199First create a new EC2 instance:

198

200

@@ -219,7 +221,7 @@ ob deploy init \

219 ~/code/myapp-deploy

221 ~/code/myapp-deploy

220```

222```

221

223

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.

223

225

224This 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.

226This 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.

225

227

@@ -234,6 +236,26 @@ ob deploy push

234

236

235At 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`.

237At 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`.

236

238

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+

237### From macOS

259### From macOS

238

260

239Deploying from macOS requires some extra setup:

261Deploying from macOS requires some extra setup:

@@ -247,7 +269,7 @@ Running `ob deploy push` will give you additional setup instructions.

247

269

248If 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:

270If 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:

249

271

250−```

272+```shell

251cd ~/code/myapp-deploy

273cd ~/code/myapp-deploy

252ob deploy update

274ob deploy update

253ob deploy push

275ob deploy push

@@ -273,14 +295,14 @@ These versions will work out of the box but iOS SDKs prior to 11.3 should also w

273

295

274More recent Xcodes should also work, as long as one of the SDKs mentioned above has been used.

296More recent Xcodes should also work, as long as one of the SDKs mentioned above has been used.

275To 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.

297To 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

277open -W Xcode_9.2.xip

299open -W Xcode_9.2.xip

278sudo 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

300sudo 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

279```

301```

280

302

281

303

282You can verify that you have correct versions by running

304You can verify that you have correct versions by running

283−```

305+```shell

284xcodebuild -showsdks

306xcodebuild -showsdks

285```

307```

286

308

@@ -306,7 +328,7 @@ Ensure that `bundleIdentifier` matches the App ID of the development profile, or

3061. Connect the registered iPhone.

3281. Connect the registered iPhone.

3071. Find your Apple Team ID in the [developer portal](https://developer.apple.com/account/#/membership).

3291. Find your Apple Team ID in the [developer portal](https://developer.apple.com/account/#/membership).

3081. Run the deploy command with your Team ID:

3301. Run the deploy command with your Team ID:

309−```

331+```shell

310result-ios/bin/deploy [TEAM_ID]

332result-ios/bin/deploy [TEAM_ID]

311# or in debug mode via lldb:

333# or in debug mode via lldb:

312result-ios/bin/deploy [TEAM_ID] -d

334result-ios/bin/deploy [TEAM_ID] -d

@@ -316,7 +338,7 @@ result-ios/bin/deploy [TEAM_ID] -d

3161. Go to [developer portal - distribution profiles](https://developer.apple.com/account/ios/profile/production).

3381. Go to [developer portal - distribution profiles](https://developer.apple.com/account/ios/profile/production).

317Create and download a distribution profile.

339Create and download a distribution profile.

3181. Run the package script with your TEAM ID and your distribution profile to create a `.ipa`:

3401. Run the package script with your TEAM ID and your distribution profile to create a `.ipa`:

319−```

341+```shell

320result-ios/bin/package [TEAM_ID] /path/to/output/.ipa /path/to/profile/file

342result-ios/bin/package [TEAM_ID] /path/to/output/.ipa /path/to/profile/file

321```

343```

322

344