1**Attention, please.**
2
3This code is a work in progress, and we publish it for full transparency. You can review the source code, but:
4
5 - you shouldn't just run this code without reading it, as it may have bugs or stubbed out crypto
6 - it might not do exactly what it says it is doing
7
8If you really want to install Keybase, please return to the [top level Readme.md](https://github.com/keybase/client/blob/master/README.md) for official release instructions.
9
10----------
11
12## Keybase
13
14### Install
15Run within the `shared/` directory.
16
17```sh
18yarn modules
19```
20Which is just an alias to run `yarn install --pure-lockfile --ignore-optional`.
21
22### Desktop
23
24The following `yarn run` commands, to build, run or package the app:
25
26| Command | Description |
27|---------|-------------|
28| start | Build a development bundle and start app |
29| hot-server | Start the hot-reloading server |
30| start-hot | Connect to a hot-reloading server (If you're developing and want to see changes as you make them) |
31| build-dev | Build development bundle |
32| build-prod | Build prod bundle |
33| package | Package app |
34
35
36You can set environment variables for debugging:
37
38| Env     | Description |
39|---------|-------------|
40| KEYBASE_RUN_MODE | Run mode: prod, staging, devel |
41| NO_DASHBOARD | Don't show dashboard |
42| KEYBASE_DEVEL_USE_XDG | Force Keybase to use XDG paths, can fix service socket location issues on Linux |
43
44You can also edit `~/Library/Logs/Keybase.app.debug` on macOS,
45`$HOME/.cache/keybase/keybase.app.debug` on Linux, or
46`%localappdata%\Keybase\keybase.app.debug` on Windows (see
47`platform.desktop.js`) to add debug flags. In particular, you probably want
48```json
49{
50  "showDevTools": true
51}
52```
53instead of toggling the dev tools after launch because of a bug where
54not all source files are available if the dev tools aren't opened at launch.
55
56### Debugging with React Developer Tools and Immutable.js Object Formatter extensions
57
581) Install the [React Developer
59Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi)
602) Set the following environment variables and make sure
61`KEYBASE_PERF` is unset. If you're using fish shell on macOS:
62
63```
64set -e KEYBASE_PERF
65set -x KEYBASE_LOCAL_DEBUG 1
66set -x KEYBASE_DEV_TOOL_ROOTS "$HOME/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi"
67```
68
69If you're using fish shell on Linux:
70
71```
72set -e KEYBASE_PERF
73set -x KEYBASE_LOCAL_DEBUG 1
74set -x KEYBASE_DEV_TOOL_ROOTS "$HOME/.config/google-chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi"
75```
76
77If you're using bash on macOS:
78
79```
80unset KEYBASE_PERF
81export KEYBASE_LOCAL_DEBUG=1
82export KEYBASE_DEV_TOOL_ROOTS="$HOME/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi"
83```
84
85If you're using bash on Linux:
86
87```
88unset KEYBASE_PERF
89export KEYBASE_LOCAL_DEBUG=1
90export KEYBASE_DEV_TOOL_ROOTS=",$HOME/.config/google-chrome/Default/Extensions/hgldghadipiblonfkkicmgcbbijnpeog"
91```
92
93(See [this code](https://github.com/keybase/client/blob/master/shared/desktop/yarn-helper/electron.js#L47) for details.)
94
953) Run `yarn run start-hot`.
96
97If you're running Chromium instead of Google Chrome, or if you've
98installed the extension in your non-default browser, you'll have to
99change the path passed to `KEYBASE_DEV_TOOL_ROOTS`.
100
101If for some reason you don't want to use `start-hot`, you'll have to
102set `KEYBASE_DEV_TOOL_EXTENSIONS` instead of `KEYBASE_DEV_TOOL_ROOTS`,
103and you'll have to use the version subdirectory:
104
105```
106set -x KEYBASE_DEV_TOOL_EXTENSIONS "$HOME/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/2.5.2_0"
107```
108
109Note that this means you'll have to change the last path component if
110Chrome updates the extension, which can happen at any time. (See [this
111code](https://github.com/keybase/client/blob/7e9ad67c0f86a82649f2e81586986892adcdf6fa/shared/desktop/app/dev-tools.js)
112and [the Electron
113docs](https://electron.atom.io/docs/tutorial/devtools-extension/) for
114details.)
115
116Then you can run, e.g. `yarn run start`.
117
1184) Make sure to check 'Enable custom formatters' in the DevTools settings for Immutable.js Object Formatter.
119
120## Android
121see [Android Docs](docs/android/overview.md)
122
123### iOS
124see [iOS docs](./docs/ios/running.md)
125
126### Troubleshooting
127
128#### Android
129[Android Troubleshooting](docs/react-native/running.md#troubleshooting)
130
131#### React Native
132[React Native Troubleshooting](docs/react-native/troubleshooting.md)
133
134### Updating `react-native`
135
136Look at [this page](https://react-native-community.github.io/upgrade-helper/) to help see what you need to change locally
137
138### Updating `electron`
139
140We host the electron binaries used for our build process in keybase.pub. If you update versions copy files from https://github.com/electron/electron/releases/ to https://keybase.pub/kbelectron/electron-download/v{version}. Make sure to get the SHASUM256.txt file also. This only affects the build machines
141
142## Storybook
143
144The app uses [storybook](https://storybook.js.org/) snapshots. If you make a change that changes the html output of a story, tests will catch the difference.
145
146To update the stories, first determine which stories changed. Run the tests `yarn test Storyshots` and look for lines containing '●':
147
148Run the local storybook server. Verify that the affected stories look correct.
149
150```
151yarn storybook
152```
153
154To update the snapshot file run:
155
156```
157yarn test -u Storyshots
158```
159
160## Misc
161
162### Updating the list of countries with SMS support
163
164In order to update the list of countries supported by Amazon SNS, run
165the [update-data.sh](https://github.com/keybase/client/blob/master/shared/util/phone-numbers/sms-support/update-data.sh)
166script. It will first fetch the JSON from Amazon's public S3 bucket and
167transform it for use in our internal country filtering code.
168
169### ESLint in VSCode
170
171VSCode's ESLint extension needs to know where to look for .eslintrc. Add this to `REPO/.vscode/settings.json`.
172
173```
174{ "eslint.workingDirectories": ["shared"] }
175```
176
177### React Devtools standalone
178
179If you want to use react devtools to examine the DOM of a running RN app in the simulator, you'll need:
180
181```
182yarn global add react-devtools@3
183```
184
185### Watchman
186
187You'll need to have watchman installed if you're running out of file descriptors:
188
189```
190brew install watchman
191```
192