diff options
Diffstat (limited to 'subprojects/docs/versioned_docs/version-0.1.0/learn/docker/index.md')
-rw-r--r-- | subprojects/docs/versioned_docs/version-0.1.0/learn/docker/index.md | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/subprojects/docs/versioned_docs/version-0.1.0/learn/docker/index.md b/subprojects/docs/versioned_docs/version-0.1.0/learn/docker/index.md new file mode 100644 index 00000000..5120095d --- /dev/null +++ b/subprojects/docs/versioned_docs/version-0.1.0/learn/docker/index.md | |||
@@ -0,0 +1,174 @@ | |||
1 | --- | ||
2 | SPDX-FileCopyrightText: 2024 The Refinery Authors | ||
3 | SPDX-License-Identifier: EPL-2.0 | ||
4 | autogenerated_sidebar_hidden: true | ||
5 | sidebar_position: 100 | ||
6 | sidebar_label: Docker | ||
7 | --- | ||
8 | |||
9 | # Running in Docker | ||
10 | |||
11 | :::note | ||
12 | |||
13 | Refinery can run as a cloud-based _Graph Solver as a Service_ without local installation. | ||
14 | If you're just looking to try Refinery, our [online demo](https://refinery.services/) provides a seamless experience without installation. | ||
15 | |||
16 | ::: | ||
17 | |||
18 | :::info | ||
19 | |||
20 | Installing Refinery as a Docker container can support more advanced use cases, such as when generating models with more resources or a longer timeout. | ||
21 | |||
22 | ::: | ||
23 | |||
24 | To generate larger models with a longer timeout, you can use our [Docker container](https://github.com/graphs4value/refinery/pkgs/container/refinery) on either `amd64` or `arm64` machines: | ||
25 | |||
26 | ```shell | ||
27 | docker run --rm -it -p 8888:8888 ghcr.io/graphs4value/refinery:0.1.0 | ||
28 | ``` | ||
29 | |||
30 | Once Docker pulls and starts the container, you can navigate to http://localhost:8888 to open the model generation interface and start editing. | ||
31 | |||
32 | A [command-line interface (CLI)](cli) version of Refinery is also available as a Docker container. | ||
33 | |||
34 | Alternatively, you can follow the [instructions to set up a local development environment](/develop/contributing) and compile and run Refinery from source. | ||
35 | |||
36 | ## Environmental variables | ||
37 | |||
38 | The Docker container supports the following environmental variables to customize its behavior. | ||
39 | Customizing these variables should only be needed if you want to _increase resource limits_ or _expose your Refinery instance over the network_ for others. | ||
40 | |||
41 | Notes for **local-only instances** are highlighted with the :arrow_right: arrow emoji. | ||
42 | |||
43 | Important security notices for **public instances** are highlighted with the :warning: warning emoji. | ||
44 | |||
45 | ### Networking | ||
46 | |||
47 | #### `REFINERY_LISTEN_HOST` | ||
48 | |||
49 | Hostname to listen at for incoming HTTP connections. | ||
50 | |||
51 | **Default value:** `0.0.0.0` (accepts connections on any IP address) | ||
52 | |||
53 | #### `REFINERY_LISTEN_PORT` | ||
54 | |||
55 | TCP port to listen at for incoming HTTP connections. | ||
56 | |||
57 | Refinery doesn't support HTTPS connections out of the box, so there's no point in setting this to `443`. Use a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) instead if you wish to expose Refinery to encrypted connections. | ||
58 | |||
59 | If you change this value, don't forget to adjust the `-p 8888:8888` option of the `docker run` command to [expose](https://docs.docker.com/reference/cli/docker/container/run/#publish) the selected port. | ||
60 | |||
61 | **Default value:** `8888` | ||
62 | |||
63 | #### `REFINERY_PUBLIC_HOST` | ||
64 | |||
65 | Publicly visible hostname of the Refinery instance. | ||
66 | |||
67 | :arrow_right: For installations only accessed locally (i.e., `localhost:8888`) without any reverse proxy, you can safely leave this empty. | ||
68 | |||
69 | :warning: You should set this to the publicly visible hostname of your Refinery instance if you wish to expose Refinery over the network. Most likely, this will be the hostname of a reverse proxy that terminates TLS connections. Our online demo sets this to [refinery.services](https://refinery.services/). | ||
70 | |||
71 | **Default value:** _empty_ | ||
72 | |||
73 | #### `REFINERY_PUBLIC_PORT` | ||
74 | |||
75 | Publicly visible port of the Refinery instance. | ||
76 | |||
77 | :arrow_right: For installations only accessed locally (i.e., `localhost:8888`), this value is ignored because `REFINERY_PUBLC_HOST` is not set. | ||
78 | |||
79 | **Default value:** `443` | ||
80 | |||
81 | #### `REFINERY_ALLOWED_ORIGINS` | ||
82 | |||
83 | Comma-separated list of allowed origins for incoming WebSocket connections. If this variable is empty, all incoming WebSocket connections are accepted. | ||
84 | |||
85 | :arrow_right: For installations only accessed locally (i.e., `localhost:8888`) without any reverse proxy, you can safely leave this empty. | ||
86 | |||
87 | :warning: The value inferred from `REFINERY_PUBLIC_HOST` and `REFINERY_PUBLIC_PORT` should be suitable for instances exposed over the network. For security reasons, public instances should never leave this empty. | ||
88 | |||
89 | **Default value:** equal to `REFINERY_PUBLIC_HOST:REFINERY_PUBLIC_PORT` if they are both set, _empty_ otherwise | ||
90 | |||
91 | ### Timeouts | ||
92 | |||
93 | #### `REFINERY_SEMANTICS_TIMEOUT_MS` | ||
94 | |||
95 | Timeout for partial model semantics calculation in milliseconds. | ||
96 | |||
97 | :arrow_right: Increase this if you have a slower machine and the editor times out before showing a preview of your partial model in the _Graph_ or _Table_ views. | ||
98 | |||
99 | :warning: Increasing this timeout may increase server load. Excessively large timeout may allow users to overload you server by entering extremely complex partial models. | ||
100 | |||
101 | **Default value:** `1000` | ||
102 | |||
103 | #### `REFINERY_SEMANTICS_WARMUP_TIMEOUT_MS` | ||
104 | |||
105 | Timeout for partial model semantics calculation in milliseconds when the server first start. | ||
106 | |||
107 | Due to various initialization tasks, the first partial model semantics generation may take longer the `REFINERY_SEMANTICS_TIMEOUT_MS` and display a timeout error. This setting increases the timeout for the first generation, leading to seamless use even after server start (especially in auto-scaling setups). | ||
108 | |||
109 | **Default value:** equal to 2 × `REFINERY_SEMANTICS_TIMEOUT` | ||
110 | |||
111 | #### `REFINERY_MODEL_GENERATION_TIMEOUT_SEC` | ||
112 | |||
113 | Timeout for model generation in seconds. | ||
114 | |||
115 | :arrow_right: Adjust this value if you're generating very large models (> 10000 nodes) and need more time to complete a generation. Note that some _unsatisfiable_ model generation problems cannot be detected by Refinery and will result in model generation running for an arbitrarily long time without producing any solution. | ||
116 | |||
117 | :warning: Long running model generation will block a [_model generation thread_](#refinery_model_generation_thread_count). Try to balance the number of threads and the timeout to avoid exhausting system resources, but keep the wait time for a free model generation thread for users reasonably short. Auto-scaling to multiple instances may help with bursty demand. | ||
118 | |||
119 | **Default value:** `600` (10 minutes) | ||
120 | |||
121 | ### Threading | ||
122 | |||
123 | :arrow_right: If you only run a single model generation task at a time, you don't need to adjust these settings. | ||
124 | |||
125 | :warning: Excessively large thread counts may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. | ||
126 | |||
127 | #### `REFINERY_XTEXT_THREAD_COUNT` | ||
128 | |||
129 | Number of threads used for non-blocking text editing operations. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. | ||
130 | |||
131 | **Default value:** `1` | ||
132 | |||
133 | #### `REFINERY_XTEXT_LOCKING_THREAD_COUNT` | ||
134 | |||
135 | Number of threads used for text editing operations that lock the document. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. | ||
136 | |||
137 | **Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` | ||
138 | |||
139 | #### `REFINERY_XTEXT_SEMANTICS_THREAD_COUNT` | ||
140 | |||
141 | Number of threads used for model semantics calculation. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. | ||
142 | |||
143 | Must be at least as large as `REFINERY_XTEXT_THREAD_COUNT`. | ||
144 | |||
145 | **Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` | ||
146 | |||
147 | #### `REFINERY_MODEL_GENERATION_THREAD_COUNT` | ||
148 | |||
149 | Number of threads used for model semantics calculation. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. | ||
150 | |||
151 | :warning: Each model generation task may also demand a large amount of memory in addition to CPU time. | ||
152 | |||
153 | **Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` | ||
154 | |||
155 | ### Libraries | ||
156 | |||
157 | #### `REFINERY_LIBRARY_PATH` | ||
158 | |||
159 | Modules (`.refinery` files) in this directory or colon-separated list of directories will be exposed to user via Refinery's `import` mechanism. | ||
160 | |||
161 | :arrow_right: Use this in conjunction with the [mount volume (-v)](https://docs.docker.com/reference/cli/docker/container/run/#volume) option of `docker run` to work with multi-file projects in Refinery. | ||
162 | |||
163 | :warning: Only expose files that you want to make public. It's best to expose a directory that contains nothing other than `.refinery` files to minimize potential information leaks. | ||
164 | |||
165 | **Default value:** _empty_ (no directories are exposed) | ||
166 | |||
167 | ## Pre-release versions | ||
168 | |||
169 | You can take advantage of the most recent code submitted to our repository by using the `latest` tag instead. | ||
170 | |||
171 | |||
172 | ```shell | ||
173 | docker run --pull always --rm -it -p 8888:8888 ghcr.io/graphs4value/refinery:latest | ||
174 | ``` | ||