Skip to content

Commit 223b9ec

Browse files
brendangaddbrendangadd
committed
docs: Update README
1 parent 90a1e14 commit 223b9ec

File tree

1 file changed

+92
-48
lines changed

1 file changed

+92
-48
lines changed

‎README.md

Lines changed: 92 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,115 @@
11
[(Français)](#interface-de-programmation-dapplications-jupyter)
22

3-
## Jupyter Application Programming Interfaces
3+
# Jupyter Application Programming Interfaces
44

5-
A Golang replacement for the [Kubeflow](https://github.com/kubeflow/kubeflow) Jupyter Web APIs.
5+
A Golang replacement for the [Kubeflow][] Jupyter Web APIs.
66

7-
### How to Contribute
7+
## How to Contribute
88

99
See [CONTRIBUTING.md](CONTRIBUTING.md)
1010

11-
### License
11+
## Developement Environment
12+
13+
### Run API Server
14+
15+
The API server will connect to the Kubeflow cluster from your current `kubectl`
16+
context. See _Connecting a Kubeflow cluster_ below for options.
17+
18+
1. [Install Go][]
19+
2. Change directory to project root: `cd jupyter-apis`
20+
3. Run `go run . -spawner-config samples/spawner_ui_config.yaml` (or use an
21+
alternative YAML config)
22+
23+
### Run Front-End
24+
25+
The front-end is configured to proxy requests to the local API server. It
26+
requires an environment variable (`KF_USER_ID`) to specify the current user –
27+
this is passed to the API server as an HTTP header.
28+
29+
1. Change directory to front-end folder: `cd frontend`
30+
2. Install dependencies: `npm install`
31+
3. Run the front-end `KF_USER_ID=<profile_name> npm start`
32+
33+
The front-end is now available at `http://localhost:4200/jupyter/`. Since it is
34+
disconnected from the `centraldashboard` component, you need to type your
35+
desired namespace in the UI rather than selecting it from a dropdown.
36+
37+
### Connecting a Kubeflow Cluster
38+
39+
The API server will connect to the Kubeflow cluster from your current `kubectl`
40+
context. Here are a couple options for setting that up.
41+
42+
#### Local miniKF Cluster (Preferred)
1243

13-
Unless otherwise noted, the source code of this project is covered under Crown Copyright, Government of Canada, and is distributed under the [MIT License](LICENSE).
44+
This deploys a Kubeflow cluster on your local machine and requires at least 50GB
45+
of disk space. First, create the miniKF cluster:
1446

15-
The Canada wordmark and related graphics associated with this distribution are protected under trademark law and copyright law. No permission is granted to use them outside the parameters of the Government of Canada's corporate identity program. For more information, see [Federal identity requirements](https://www.canada.ca/en/treasury-board-secretariat/topics/government-communications/federal-identity-requirements.html).
47+
1. Install Vagrant and Virtual Box.
48+
2. Create a new directory and run `vagrant init arrikto/minikf` and then
49+
`vagrant up` (takes about 20 minutes to boot).
50+
3. Navigate to `http://10.10.10.10`.
51+
4. Follow on-screen steps to start Kubeflow and Rok (takes about another 20
52+
minutes).
53+
5. From here, you can use Kubeflow and Rok.
54+
55+
Then configure `kubectl` to connect to your new cluster:
56+
57+
1. Download the miniKF `kubectl` config file from `http://10.10.10.10`.
58+
2. Use the downloaded configuration for `kubectl`, either replacing, or merging
59+
it into, `~/.kube/config`.
60+
3. Ensure `kubectl config current-context` is pointing to your local cluster.
61+
62+
Your `KF_USER_ID` can be the default user that was created for your miniKF
63+
cluster (typically `user`).
64+
65+
Each time you need to start the cluster, navigate to the directory you created
66+
and run `vagrant up`.
67+
68+
#### Remote AKS Cluster
1669

17-
## Developement
18-
_Set up CLI tools to interact with Kubernetes (connect to remote AKS cluster):_
1970
1. Install Azure CLI `az` and `kubectl`
2071
2. Login with `az` and set your subscription
2172
3. Run `az aks get-credentials` for the desired remote cluster
22-
4. Clone this repository
23-
24-
_Frontend:_
25-
1. Install `Go`
26-
2. From `jupyter-apis/`, run `. -spawner-config samples/spawner_ui_config.yaml`
27-
3. From `jupyter-apis/frontend`, run `npm install`
28-
- This will install all of the project dependencies and prepare your system for development.
29-
4. To start a development environment, run `npm start`
30-
- This runs [webpack](https://webpack.js.org/) over the front-end code and starts
31-
the dev-server at http://localhost:4200/jupyter/.
32-
5. Open browser to `http://localhost:4200/jupyter/`, update Namespace.
33-
34-
### Connect this jupyter-apis component to local instance of Kubeflow:
35-
_Set up local Kubeflow cluster using [MiniKF](https://www.kubeflow.org/docs/started/workstation/getting-started-minikf/):_
36-
37-
Note: Need at least 50GB of disk space
38-
1. Install Vagrant and Virtual Box
39-
2. Create a new directory and run `vagrant init arrikto/minikf` and then `vagrant up` (takes about 20 minutes to boot)
40-
3. Navigate to http://10.10.10.10
41-
4. Follow on-screen steps to start Kubeflow and Rok (takes about another 20 minutes)
42-
5. From here, you can use Kubeflow and Rok
43-
44-
_Configure a `kubectl` context for that cluster:_
45-
1. Have `kubectl` CLI set up and `Go` installed
46-
2. From http://10.10.10.10, download the MiniKF kubeconfig file
47-
- Can either move this file into your `.kube/` directory and rename it to `config` or can change the default config file name and path in [`main.go`](https://github.com/StatCan/jupyter-apis/blob/master/main.go#L69) to the path and name of the `minikf-kubeconfig` downloaded file
48-
3. From `jupyter-apis/`, run `. -spawner-config samples/spawner_ui_config.yaml`
49-
- Can update the [YAML file](https://github.com/StatCan/jupyter-apis/blob/master/samples/spawner_ui_config.yaml#L17) if you want to put your custom images into the notebook server image dropdown list.
50-
4. From `jupyter-apis/frontend` folder, run `npm install` and `KF_USER_ID=<username given by MiniKF> npm start`
51-
- Usually, the `KF_USER_ID` will be `user` because that may be the default username MiniKF always gives
52-
5. Navigate to http://localhost:4200/jupyter/
53-
6. Set Namespace to `kubeflow-user`
54-
55-
**To connect to MiniKF, have to go into directory created and run `vagrant up` every time, then navigate to http://10.10.10.10**
56-
57-
______________________
73+
4. Ensure `kubectl config current-context` is pointing to the correct AKS
74+
cluster
75+
76+
### License
77+
78+
Unless otherwise noted, the source code of this project is covered under Crown
79+
Copyright, Government of Canada, and is distributed under the
80+
[MIT License](LICENSE).
81+
82+
The Canada wordmark and related graphics associated with this distribution are
83+
protected under trademark law and copyright law. No permission is granted to use
84+
them outside the parameters of the Government of Canada's corporate identity
85+
program. For more information, see [Federal identity requirements][].
86+
87+
---
5888

5989
## Interface de programmation d'applications Jupyter
6090

61-
Un remplacement Golang pour les API de Web de Jupyter, partie de [Kubeflow](https://github.com/kubeflow/kubeflow).
91+
Un remplacement Golang pour les API de Web de Jupyter, partie de [Kubeflow][].
6292

6393
### Comment contribuer
6494

6595
Voir [CONTRIBUTING.md](CONTRIBUTING.md)
6696

6797
### Licence
6898

69-
Sauf indication contraire, le code source de ce projet est protégé par le droit d'auteur de la Couronne du gouvernement du Canada et distribué sous la [licence MIT](LICENSE).
70-
71-
Le mot-symbole « Canada » et les éléments graphiques connexes liés à cette distribution sont protégés en vertu des lois portant sur les marques de commerce et le droit d'auteur. Aucune autorisation n'est accordée pour leur utilisation à l'extérieur des paramètres du programme de coordination de l'image de marque du gouvernement du Canada. Pour obtenir davantage de renseignements à ce sujet, veuillez consulter les [Exigences pour l'image de marque](https://www.canada.ca/fr/secretariat-conseil-tresor/sujets/communications-gouvernementales/exigences-image-marque.html).
99+
Sauf indication contraire, le code source de ce projet est protégé par le droit
100+
d'auteur de la Couronne du gouvernement du Canada et distribué sous la
101+
[licence MIT](LICENSE).
102+
103+
Le mot-symbole « Canada » et les éléments graphiques connexes liés à cette
104+
distribution sont protégés en vertu des lois portant sur les marques de commerce
105+
et le droit d'auteur. Aucune autorisation n'est accordée pour leur utilisation à
106+
l'extérieur des paramètres du programme de coordination de l'image de marque du
107+
gouvernement du Canada. Pour obtenir davantage de renseignements à ce sujet,
108+
veuillez consulter les [Exigences pour l'image de marque][].
109+
110+
[exigences pour l'image de marque]:
111+
https://www.canada.ca/fr/secretariat-conseil-tresor/sujets/communications-gouvernementales/exigences-image-marque.html
112+
[federal identity requirements]:
113+
https://www.canada.ca/en/treasury-board-secretariat/topics/government-communications/federal-identity-requirements.html
114+
[install go]: https://golang.org/dl/
115+
[kubeflow]: https://github.com/kubeflow/kubeflow

0 commit comments

Comments
 (0)