git.iko.soy/bridge
on master help sign in
Merge pull request #206 from urbit/mino-readme
a77fa97Fang
DEVELOPMENT.mdnew file+99
compare with master
unifiedsplit
@@ -0,0 +1,99 @@
1+# Development notes
2+
3+## Install / Build
4+
5+Clone the repo, and use a simple `npm install`. You can then use a `npm run build` to create an optimised static build (serve it with e.g. [serve](http://npmjs.com/package/serve), or with python as described above).
6+
7+## General notes
8+
9+For development, use `npm run pilot` to get going after a `npm install`. This
10+will boot up a [Ganache](https://github.com/trufflesuite/ganache-cli) node in the background, deploy the Azimuth contracts to
11+it, and fire up a local webserver. Bridge will be served on `localhost:3000`.
12+
13+Note that one of our dependencies itself depends on a library called
14+`handle-thing` which breaks under the Ledger support requirements (see below)
15+on node 11.1.0, so make sure you're using some other node version.
16+
17+You can use [nvm](https://github.com/creationix/nvm), for example, and do:
18+
19+```
20+$ nvm install 11.0.0
21+$ nvm use v11.0.0
22+```
23+
24+before running `npm run pilot`.
25+
26+## Useful accounts
27+
28+The ecliptic owner is the only account that's able to create galaxies, so
29+it's a good place to get started. On the testnet, it's the address:
30+
31+```
32+0x6DEfFb0caFDB11D175F123F6891AA64F01c24F7d
33+```
34+
35+You can authenticate as it using the following mnemonic:
36+
37+```
38+benefit crew supreme gesture quantum web media hazard theory mercy wing kitten
39+```
40+
41+Under that mnemonic, Ganache will also auto-populate the following accounts
42+with 100 ETH:
43+
44+```
45+0x6deffb0cafdb11d175f123f6891aa64f01c24f7d
46+0xd53208cf45fc9bd7938b200bff8814a26146688f
47+0x7b2a2d51e4d8fac602e20a5f6907ff9fbd88e1fd
48+0xf48062ae8bafd6ef19cd6cb89db93a0d0ca6ce26
49+0xf84a77aeb351c49dfa87e805a659d2daddff7606
50+0x167e357cf8b845370d0d408f9b389b66185b7b5b
51+0xcbecf3abc9878f07afc851aead2d8f1c436cc71d
52+0x0afc0c3f4eeea500871f464ca71eef5e54a9af36
53+0x6d654ef2489674d21aed428e8a4ad8ca4820f125
54+0x218f6f87683db546ad47a5dc8b480e5a9b694866
55+```
56+
57+To play around with any of these, authenticate using the same mnemonic, but
58+use a custom HD path of `m/44'/60'/0'/0/1`, `m/44'/60'/0'/0/2`, and so on.
59+
60+## Initial development state
61+
62+You can also tweak a couple of things to change your development state
63+somewhat (say, for example, you want to start on the points list screen, instead
64+of having to re-authenticate whenever you make a change or refresh the page):
65+
66+- The `.env.development` file contains environment variables that you can
67+ provide to the application when it's running in development. You can access
68+ them via `process.env.REACT_APP_<whatever>`.
69+
70+- Set `REACT_APP_STUB_LOCAL='true'` in `.env.development` to enabled stubbing of
71+ certain methods throughout the app.
72+
73+- The top of the Bridge component in `src/Bridge.js` can be tweaked for setting
74+ your initial state. You can provide a specific wallet,
75+ network type, and so on.
76+
77+## HTTPS
78+
79+For development, you can enable HTTPS on localhost without a certificate for
80+Chrome by pasting the following into the URL bar:
81+
82+```
83+chrome://flags/#allow-insecure-localhost
84+```
85+
86+In Firefox, you may need to allow connecting to the unsecured local node
87+websocket. Do this by going to `about:config` and setting the
88+`network.websocket.allowInsecureFromHTTPS` flag to `true`.
89+
90+Additionally you need to run with the `HTTPS` environment variable set to
91+`true`. Note that `npm run pilot` will handle this automatically.
92+
93+## Releases
94+
95+To generate a release `bridge-$VERSION.zip` file, use a simple `npm run release`.
96+
97+This will pack the build directory together with the README, `bridge-https.py`
98+script, and also generate a set of checksums for the build directory. You can
99+verify the checksums on e.g. MacOS via `shasum -c checksums.txt`.
README.md+23−119
@@ -6,147 +6,51 @@ An application for interacting with Azimuth.
6
6
7## Usage
7## Usage
8
8
9+The latest version of Bridge is accessible online at [bridge.azimuth.network](https://bridge.azimuth.network). No setup needed.
10+
11+If you would rather host Bridge on your own machine, read on.
12+
9### Requirements
13### Requirements
10
14
11Python 3.7.2
15Python 3.7.2
12
16
13### Instructions
17### Instructions
14
18
15−#### Install
19+#### Download
16
20
17−1. [Download a release](https://github.com/urbit/bridge/releases)
21+1. [Download a release](https://github.com/urbit/bridge/releases/latest)
182. Unzip it (`bridge-$version.zip`)
222. Unzip it (`bridge-$version.zip`)
193. Open up your command line interface (Terminal on MacOS, Command Prompt on Windows)
233. Open up your command line interface (Terminal on MacOS, Command Prompt on Windows)
204. `cd` into the `bridge-$version` directory
244. `cd` into the `bridge-$version` directory
21
25
22−Follow the instructions below to run Bridge.
26+#### Verify checksums
23−
24−#### Run Bridge
25
27
26−If you plan to authenticate and sign transactions with a Master Ticket, BIP39 mnemonic, Ethereum private key, or keystore file:
27−
28−1. `cd` into the `bridge-$version` directory
29−2. Run `python3 -m http.server 5000 --bind 127.0.0.1`
30−3. Navigate to http://localhost:5000 using a web browser to access Bridge (we recommend using Firefox or Chrome)
31−
32−#### Run Bridge with Ledger support
33−
34−If you plan to authenticate and sign transactions with a [Ledger](https://www.ledger.com/), Bridge must be serving over HTTPS on localhost. This requires self-signed certificates. To do this:
35−
36−1. Install [mkcert](https://github.com/FiloSottile/mkcert)
37−2. If you're using Firefox, additionally install [nss](https://github.com/nss-dev/nss)
38−3. Install a local certificate authority via `mkcert -install`
39−4. From the `bridge-$version` directory, run `mkcert localhost` to generate a certificate valid for localhost. This will produce two files: `localhost.pem`, the local certificate, and `localhost-key.pem`, its corresponding private key
40−5. Run `python bridge-https.py`
41−6. Navigate to https://localhost:4443 in a web browser to access Bridge
42−
43−### Verify checksums
44−
45−To validate your downloaded file's integrity, compare the lines in checksum.txt to SHA-256 hashes of the `bridge-$version` directory's contents.
28+Optionally, to validate your downloaded file's integrity, compare the lines in checksum.txt to SHA-256 hashes of the `bridge-$version` directory's contents.
46
29
47- On MacOS: `shasum -a 256 -c checksums.txt .`
30- On MacOS: `shasum -a 256 -c checksums.txt .`
48- On Linux: `sha256sum -c checksums.txt .`
31- On Linux: `sha256sum -c checksums.txt .`
49- On Windows: Go into the `build` directory and verify files individually with `CertUtil -hashFile [file_name] SHA256`
32- On Windows: Go into the `build` directory and verify files individually with `CertUtil -hashFile [file_name] SHA256`
50
33
51−## Development notes
34+#### Run Bridge
52−
53−### Install / Build
54−
55−Clone the repo, and use a simple `npm install`. You can then use a `npm run build` to create an optimised static build (serve it with e.g. [serve][serv]).
56−
57−### General notes
58−
59−For development, use `npm run pilot` to get going after a `npm install`. This
60−will boot up a Ganache node in the background, deploy the Azimuth contracts to
61−it, and fire up a local webserver. Bridge will be served on `localhost:3000`.
62−
63−Note that one of our dependencies itself depends on a library called
64−`handle-thing` which breaks under the Ledger support requirements (see below)
65−on node 11.1.0, so make sure you're using some other node version.
66−
67−You can use [nvm](https://github.com/creationix/nvm), for example, and do:
68−
69−```
70−$ nvm install 11.0.0
71−$ nvm use v11.0.0
72−```
73−
74−before running `npm run pilot`.
75−
76−### Useful accounts
77−
78−The ecliptic owner is the only account that's able to create galaxies, so
79−it's a good place to get started. On the testnet, it's the address:
80−
81−```
82−0x6DEfFb0caFDB11D175F123F6891AA64F01c24F7d
83−```
84−
85−You can authenticate as it using the following mnemonic:
86−
87−```
88−benefit crew supreme gesture quantum web media hazard theory mercy wing kitten
89−```
90−
91−Under that mnemonic, Ganache will also auto-populate the following accounts
92−with 100 ETH:
93−
94−```
95−0x6deffb0cafdb11d175f123f6891aa64f01c24f7d
96−0xd53208cf45fc9bd7938b200bff8814a26146688f
97−0x7b2a2d51e4d8fac602e20a5f6907ff9fbd88e1fd
98−0xf48062ae8bafd6ef19cd6cb89db93a0d0ca6ce26
99−0xf84a77aeb351c49dfa87e805a659d2daddff7606
100−0x167e357cf8b845370d0d408f9b389b66185b7b5b
101−0xcbecf3abc9878f07afc851aead2d8f1c436cc71d
102−0x0afc0c3f4eeea500871f464ca71eef5e54a9af36
103−0x6d654ef2489674d21aed428e8a4ad8ca4820f125
104−0x218f6f87683db546ad47a5dc8b480e5a9b694866
105−```
106−
107−To play around with any of these, authenticate using the same mnemonic, but
108−use a custom HD path of `m/44'/60'/0'/0/1`, `m/44'/60'/0'/0/2`, and so on.
109−
110−### Initial development state
111−
112−You can also tweak a couple of things to change your development state
113−somewhat (say, for example, you want to start on the points list screen, instead
114−of having to re-authenticate whenever you make a change or refresh the page):
115−
116−- The `.env.development` file contains environment variables that you can
117− provide to the application when it's running in development. You can access
118− them via `process.env.REACT_APP_<whatever>`.
119−
120−- Set `REACT_APP_STUB_LOCAL='true'` in `.env.development` to enabled stubbing of
121− certain methods throughout the app.
122−
123−- The top of the Bridge component in `src/Bridge.js` can be tweaked for setting
124− your initial state. You can provide a specific wallet,
125− network type, and so on.
126−
127−### HTTPS
128
35
129−For development, you can enable HTTPS on localhost without a certificate for
36+1. `cd` into the `bridge-$version` directory
130−Chrome by pasting the following into the URL bar:
37+2. Run `python3 -m http.server 5000 --bind 127.0.0.1`
38+3. Navigate to http://localhost:5000 using a web browser to access Bridge (we recommend using Firefox or Chrome)
131
39
132−```
40+#### Ledger support
133−chrome://flags/#allow-insecure-localhost
134−```
135
41
136−In Firefox, you may need to allow connecting to the unsecured local node
42+If you plan to authenticate with a [Ledger](https://www.ledger.com/), Bridge must be serving over HTTPS on localhost. This requires self-signed certificates. To do this:
137−websocket. Do this by going to `about:config` and setting the
138−`network.websocket.allowInsecureFromHTTPS` flag to `true`.
139
43
140−Additionally you need to run with the `HTTPS` environment variable set to
44+1. Install [mkcert](https://github.com/FiloSottile/mkcert)
141−`true`. Note that `npm run pilot` will handle this automatically.
45+2. Install a local certificate authority via `mkcert -install`
46+3. From the `bridge-$version` directory, run `mkcert localhost` to generate a certificate valid for localhost. This will produce two files: `localhost.pem`, the local certificate, and `localhost-key.pem`, its corresponding private key
47+4. Run `python bridge-https.py`
48+5. Navigate to https://localhost:4443 in a web browser to access Bridge
142
49
143−### Releases
50+## Bridge without internet access
144
51
145−To generate a release `bridge-$VERSION.zip` file, use a simple `npm run release`.
52+A proper "offline mode" for the latest iteration of Bridge is still being worked on. In the mean time, if you need to use Bridge on an airgapped machine, use [Bridge v1.4.1](https://github.com/urbit/bridge/releases/tag/v1.4.1).
146
53
147−This will pack the build directory together with the README, `bridge-https.py`
54+## Development
148−script, and also generate a set of checksums for the build directory. You can
149−verify the checksums on e.g. OS X via `shasum -c checksums.txt`.
150
55
151−[rele]: https://github.com/urbit/bridge/releases/latest
56+See [development.md](DEVELOPMENT.md).
152−[serv]: http://npmjs.com/package/serve