git.iko.soy/obelisk
on aa-graphviz-hackaround help sign in
obelisk/README.md
283 lines 12 kB history raw
1# Obelisk
3Obelisk provides an easy way to develop and deploy your [Reflex](https://github.com/reflex-frp/reflex) project as web apps and as mobile apps.
5- [Installing Obelisk](#installing-obelisk)
6- [Developing an Obelisk project](#developing-an-obelisk-project)
7- [Deploying](#deploying)
8 - [Locally](#locally)
9 - [EC2](#ec2)
10- [Mobile](#mobile)
11 - [iOS](#ios)
12 - [Android](#android)
14## Installing Obelisk
151. [Install Nix](https://nixos.org/nix/).
16 If you already have Nix installed, make sure you have version 2.0 or higher. To check your current version, run `nix-env --version`.
171. Set up nix caches
18 1. If you are running NixOS, add this to `/etc/nixos/configuration.nix`:
19 ```
20 nix.binaryCaches = [ "https://cache.nixos.org/" "https://nixcache.reflex-frp.org" ];
21 nix.binaryCachePublicKeys = [ "ryantrinkle.com-1:JJiAKaRv9mWgpVAz8dwewnZe0AzzEAzPkagE9SP5NWI=" ];
22 ```
23 1. If you are using another operating system or linux distribution, ensure that these lines are present in `/etc/nix/nix.conf`:
24 ```
25 sandbox = true
26 substituters = https://cache.nixos.org https://nixcache.reflex-frp.org
27 trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= ryantrinkle.com-1:JJiAKaRv9mWgpVAz8dwewnZe0AzzEAzPkagE9SP5NWI=
28 ```
29 * If you are on MacOS, restart the nix daemon
30 ```
31 sudo launchctl stop org.nixos.nix-daemon
32 sudo launchctl start org.nixos.nix-daemon
33 ```
341. Install obelisk: `nix-env -f https://github.com/obsidiansystems/obelisk/archive/master.tar.gz -iA command`
36### Contributing to Obelisk
38When developing on obelisk itself you may launch `ghcid` for the corresponding project as follows. For example to launch ghcid for `lib/backend` project:
40```
41nix-shell -A obelisk.obelisk-backend.env --run "cd lib/backend && ghcid -c 'cabal new-repl'"
42```
44Or to launch ghcid for `lib/command` project:
46```
47nix-shell -A obelisk.obelisk-command.env --run "cd lib/command && ghcid -c 'cabal new-repl'"
48```
50### Accessing private repositories
51To allow the Nix builder to access private git repositories, follow these steps:
531. [Get set up to connect to GitHub with SSH](https://help.github.com/articles/connecting-to-github-with-ssh/)
541. [Create a GitHub personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
551. Set environment variables:
56 * NixOS: Add this to `/etc/nixos/configuration.nix`:
57 ```
58 nix.envVars = {
59 NIX_GITHUB_PRIVATE_USERNAME = "your-github-username";
60 NIX_GITHUB_PRIVATE_PASSWORD = "your-github-personal-access-token";
61 };
62 ```
63 * MacOS:
64 ```
65 sudo launchctl setenv NIX_GITHUB_PRIVATE_USERNAME "your-github-username"
66 sudo launchctl setenv NIX_GITHUB_PRIVATE_PASSWORD "your-github-personal-access"
67 sudo launchctl stop org.nixos.nix-daemon
68 sudo launchctl start org.nixos.nix-daemon
69 ```
701. `nix-env -i hub` OR `nix-env -iA nixos.gitAndTools.hub`
711. `hub clone yourusername/yourproject`
72 * NOTE: you must authenticate with hub at least once, because the `ob` command uses `hub` for authentication
73 #TODO: Make ob do this itself (either invoke hub automatically or not depend on hub)
75## Developing an Obelisk project
77To create a new Obelisk project, go to an empty directory and run:
79```
80ob init
81```
83Obelisk 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:
85```
86ob run
87```
89Now go to http://localhost:8000 (or the port specified in `config/common/route`) to access your app.
91Every time you change the Haskell source files in frontend, common or backend, `ob run` will automatically recompile the modified files and reload the server. Furthermore, it will display on screen compilation errors and warnings if any.
93## Deploying
95### Locally
97Build everything:
99```
100nix-build -A exe -o result-exe
101```
103Run the server:
105```
106cd result-exe
107./backend
108```
110### EC2
112In this section we will demonstrate how to deploy your Obelisk app to an Amazon EC2 instance.
114First create a new EC2 instance:
1161. Launch a NixOS 17.09 EC2 instance (we recommend [this AMI](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#LaunchInstanceWizard:ami=ami-40bee63a))
1171. In the instance configuration wizard ensure that your instance has at least 1GB RAM and 10GB disk space.
1181. When prompted save your AWS private key (`~/myaws.pem`) somewhere safe. We'll need it later during deployment.
1191. Go to "Security Groups", select your instance's security group and under "Inbound" tab add a new rule for HTTP port 80 and 443.
121At this stage your instance should be booting and become accessible shortly. Note down the hostname of your EC2 instance.
123Now go to your Obelisk project directory (`~/code/myapp`), and initialize a deployment config (`~/code/myapp-deploy`):
124Your project directory must be "thunkable", i.e. something on which `ob thunk pack` can be called. Usually it will be a git repository whose current revision has been pushed upstream.
126```
127cd ~/code/myapp
128SERVER=ec2-35-183-22-197.ca-central-1.compute.amazonaws.com
129ROUTE=https://myapp.com # Publicly accessible route to your app
130EMAIL=myname@myapp.com
131ob deploy init \
132 --ssh-key ~/myaws.pem \
133 --hostname $SERVER \
134 --route $ROUTE \
135 --admin-email $EMAIL \
136 ~/code/myapp-deploy
137```
139NOTE: HTTPS is enabled by default; to disable https, pass `--disable-https` to the `ob deploy init` command above.
141Then go to that created deployment configuration directory, and initiate the deployment:
143```
144cd ~/code/myapp-deploy
145ob deploy push
146```
148`ob deploy push` will locally build your app and then transfer it, along with all the Nix package dependencies, via ssh to the EC2 instance.
150At this point you are done. Your app will be accessible at `${ROUTE}`.
152### Deploying an updated version
154If 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:
156```
157cd ~/code/myapp-deploy
158ob deploy update
159ob deploy push
160```
162## Mobile
163Until Obelisk offers a `ob deploy` equivalent for mobile apps, you are recommended to do it manually as follows.
165### iOS
167#### First time setup
168Development on iOS requires a computer running macOS and an iOS developer account.
169Your account must also belong to an Apple Developer Team, if you want to access developer portal links (otherwise they'll redirect to your account page).
171##### iPhone
1721. Connect the iPhone on which you'd like to run builds - this will open up iTunes.
1731. Click accept to authorize on both the computer and the iPhone.
175##### Xcode
176Install Xcode 8.2 (contains iOS SDK 10.2) and open it so that it runs its post install tool setup.
178These versions will work out of the box but iOS SDKs prior to 11.3 should also work. You can choose another installed version in `default.nix`
180More recent Xcodes should also work, as long as one of the SDKs mentioned above has been used.
181To 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.
182```
183open -W Xcode_9.2.xip
184sudo 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
185```
188You can verify that you have correct versions by running
189```
190xcodebuild -showsdks
191```
193##### Certificates
194To deploy and/or package apps, you'll need to inform Apple of your development devices and permissions by
195adding credentials to the correct provisioning profile via the Apple Developer portal.
1971. Open up XCode and go to Preferences - Accounts. Select the organization
198Member role, click Manage Certificates, and add an iOS Development
199certificate.
2001. Go to [developer portal - devices](https://developer.apple.com/account/ios/device/) and add your device.
201To find your device's UDID, select it in iTunes and click the serial number.
2021. Go to [developer portal - development profiles](https://developer.apple.com/account/ios/profile/limited).
203Create a development profile and add your certificate and device.
204Click "Generate" and then download and open the profile.
206#### Building
2071. In your project's `default.nix` set values for `ios.bundleIdentifier` and `ios.bundleName`.
208Ensure that `bundleIdentifier` matches the App ID of the development profile, or that you are using a wildcard profile.
2091. Run `nix-build -A ios.frontend -o result-ios` to build the app. Find it at `result-ios/frontend.app`
211#### Deploying
2121. Connect the registered iPhone.
2131. Find your Apple Team ID in the [developer portal](https://developer.apple.com/account/#/membership).
2141. Run the deploy command with your Team ID:
215```
216result-ios/bin/deploy [TEAM_ID]
217# or in debug mode via lldb:
218result-ios/bin/deploy [TEAM_ID] -d
219```
221#### Packaging
2221. Go to [developer portal - distribution profiles](https://developer.apple.com/account/ios/profile/production).
223Create and download a distribution profile.
2241. Run the package script with your TEAM ID and your distribution profile to create a `.ipa`:
225```
226result-ios/bin/package [TEAM_ID] /path/to/output/.ipa /path/to/profile/file
227```
229#### Debugging
230It's also possible to inspect iOS WkWebView apps once they are installed in the iPhone:
2311. On the desktop, go to Safari > Preferences > Advanced and enable Develop menu.
2321. On the iPhone go to Settings > Safari > Advanced and enable Web Inspector.
2331. Open the app on the iPhone while it is connected to the desktop.
2341. In the desktop's Safari Develop menu, you should see your iPhone. Select the screen under the name of the app.
236### Android
2381. In your project's `default.nix` set a suitable value for `android.applicationId` and `android.displayName`.
2391. Run `nix-build -A android.frontend -o result-android` to build the Android app.
2401. A debug version of the app should be generated at `result-android/android-app-debug.apk`
242Now deploy the built apk file to your Android device:
2441. Enable *USB debugging* in your Android device ([instructions here](https://developer.android.com/studio/debug/dev-options))
2451. Connect the device using USB (be sure to confirm any security prompts on the device)
2461. Run the deploy script: `result-android/bin/deploy`
248This should copy over and install the application on your device (if you see a "*signatures do not match*" error, simply uninstall the previous app from the device before retrying the deploy). The name of the installed application will be what you have specified for `android.displayName` in the `default.nix`.
250#### Releasing to Play Store
252##### Configure signing
254The previous section would have generated a debug version of the app. In order to build a release version you will need to sign your app. Obelisk can automatically sign the app during build if you provide it with your keystore file in `default.nix`.
256First, if you do not already have a keystore, create it as follows (for more information, see the [Android documentation](https://developer.android.com/studio/publish/app-signing#signing-manually)):
258```
259nix-shell -p androidenv.platformTools --run "keytool -genkey -v -keystore myandroidkey.jks -keyalg RSA -keysize 2048 -validity 10000 -alias myandroidalias"
260```
262(Besure to give an appropriate keystore filename and key alias string above.)
264The `keytool` command will ask you for some details, including a keystore password and a key password (we will use these passwords further below). It will now have created a `myandroidkey.jks` file under the current directory. Move that to somewhere safe, and note down its full path.
266Now edit your project's `default.nix` and tell Obelisk of your app's keystore file. Your `default.nix` should look like this after the edit:
268```nix
269 ...
270 android.applicationId = "com.example.myapp";
271 android.displayName = "My App";
272 android.releaseKey =
273 { storeFile = /path/to/myandroidkey.jks;
274 storePassword = "abcd1234";
275 keyAlias = "myandroidalias";
276 keyPassword = "abcd1234";
277 };
278 ...
279```
281##### Build a release version
283After having configured signing for your app, you may proceed to build a release version of the app. This is no different to how you build the non-release version, so consult the section [Android](#android) further above for exact instructions on building and deploying to your device.