Merge branch 'main' from workbench2.git
[arvados.git] / services / workbench2 / README.md
1 [comment]: # (Copyright © The Arvados Authors. All rights reserved.)
2 [comment]: # ()
3 [comment]: # (SPDX-License-Identifier: CC-BY-SA-3.0)
4
5 # Arvados Workbench 2
6
7 ## Setup
8 ```
9 npm install yarn
10 yarn install
11 ```
12
13 Install [redux-devtools-extension](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd)
14
15 ## Start project for development
16 ```
17 yarn start
18 ```
19
20 ## Start project for development inside Docker container
21
22 ```
23 make workbench2-build-image
24 # (create public/config.json, see "Run time configuration" below)
25 docker run -ti -v$PWD:$PWD -p 3000:3000 -w$PWD workbench2-build /bin/bash
26 # (inside docker container)
27 yarn install
28 yarn start
29 ```
30
31 ## Run unit tests
32 ```
33 make unit-tests
34 ```
35
36 ## Run end-to-end tests
37
38 ```
39 make integration-tests
40 ```
41
42 ## Run end-to-end tests in a Docker container
43
44 ```
45 make integration-tests-in-docker
46 ```
47
48 ## Run tests interactively in container
49
50 ```
51 xhost +local:root
52 ARVADOS_DIR=/path/to/arvados
53 docker run -ti -v$PWD:$PWD -v$ARVADOS_DIR:/usr/src/arvados -w$PWD --env="DISPLAY" --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" workbench2-build /bin/bash
54 (inside container)
55 yarn run cypress install
56 tools/run-integration-tests.sh -i -a /usr/src/arvados
57 ```
58
59 ## Production build
60 ```
61 yarn build
62 ```
63
64 ## Package build
65 ```
66 make packages
67 ```
68
69 ## Build time configuration
70 You can customize project global variables using env variables. Default values are placed in the `.env` file.
71
72 Example:
73 ```
74 REACT_APP_ARVADOS_CONFIG_URL=config.json yarn build
75 ```
76
77 ## Run time configuration
78 The app will fetch runtime configuration when starting. By default it will try to fetch `/config.json`.  In development mode, this can be found in the `public` directory.
79 You can customize this url using build time configuration.
80
81 Currently this configuration schema is supported:
82 ```
83 {
84     "API_HOST": "string",
85     "FILE_VIEWERS_CONFIG_URL": "string",
86 }
87 ```
88
89 ### API_HOST
90
91 The Arvados base URL.
92
93 The `REACT_APP_ARVADOS_API_HOST` environment variable can be used to set the default URL if the run time configuration is unreachable.
94
95 ## FILE_VIEWERS_CONFIG_URL
96 Local path, or any URL that allows cross-origin requests. See:
97
98 [File viewers config file example](public/file-viewers-example.json)
99
100 [File viewers config scheme](src/models/file-viewers-config.ts)
101
102 To use the URL defined in the Arvados cluster configuration, remove the entire `FILE_VIEWERS_CONFIG_URL` entry from the runtime configuration. Found in `/config.json` by default.
103
104 ## Plugin support
105
106 Workbench supports plugins to add new functionality to the user
107 interface.  For information about installing plugins, the provided
108 example plugins, see [src/plugins/README.md](src/plugins/README.md).
109
110
111 ## Licensing
112
113 Arvados is Free Software. See COPYING for information about Arvados Free
114 Software licenses.