1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
---
SPDX-FileCopyrightText: 2024 The Refinery Authors
SPDX-License-Identifier: EPL-2.0
sidebar_position: 100
sidebar_label: Docker
---
# Running in Docker
:::note
Refinery can run as a cloud-based _Graph Solver as a Service_ without local installation.
If you're just looking to try Refinery, our [online demo](https://refinery.services/) provides a seamless experience without installation.
:::
:::info
Installing Refinery as a Docker container can support more advanced use cases, such as when generating models with more resources or a longer timeout.
:::
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:
```shell
docker run --rm -it -p 8888:8888 ghcr.io/graphs4value/refinery
```
Once Docker pulls and starts the container, you can navigate to http://localhost:8888 to open the model generation interface and start editing.
Alternatively, you can follow the [instructions to set up a local development environment](/api/contributing) and compile and run Refinery from source.
## Updating
To take advantage of the latest updates, you can simply re-pull our Docker container from the GitHub Container Registry:
```shell
docker pull ghcr.io/graphs4value/refinery
```
Restart the container to make sure that you're running the last pulled version.
## Environmental variables
The Docker container supports the following environmental variables to customize its behavior.
Customizing these variable should only be needed if you want to _increase resource limits_ or _expose you Refinery instance over the network_ for others.
Notes for **local-only instances** are highlighted with the :arrow_right: arrow emoji.
Important security notices for **public instances** are highlighted with the :warning: warning emoji.
### Networking
#### `REFINERY_LISTEN_HOST`
Hostname to listen at for incoming HTTP connections.
**Default value:** `0.0.0.0` (accepts connections on any IP address)
#### `REFINERY_LISTEN_PORT`
TCP port to listen at for incoming HTTP connections.
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.
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.
**Default value:** `8888`
#### `REFINERY_PUBLIC_HOST`
Publicly visible hostname of the Refinery instance.
:arrow_right: For installations only accessed locally (i.e., `localhost:8888`) without any reverse proxy, you can safely leave this empty.
: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/).
**Default value:** _empty_
#### `REFINERY_PUBLIC_PORT`
Publicly visible port of the Refinery instance.
:arrow_right: For installations only accessed locally (i.e., `localhost:8888`), this value is ignored because `REFINERY_PUBLC_HOST` is not set.
**Default value:** `443`
#### `REFINERY_ALLOWED_ORIGINS`
Comma-separated list of allowed origins for incoming WebSocket connections. If this variable is empty, all incoming WebSocket connections are accepted.
:arrow_right: For installations only accessed locally (i.e., `localhost:8888`) without any reverse proxy, you can safely leave this empty.
: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.
**Default value:** equal to `REFINERY_PUBLIC_HOST:REFINERY_PUBLIC_PORT` if they are both set, _empty_ otherwise
### Timeouts
#### `REFINERY_SEMANTICS_TIMEOUT_MS`
Timeout for partial model semantics calculation in milliseconds.
: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.
:warning: Increasing this timeout may increase server load. Excessively large timeout may allow users to overload you server by entering extremely complex partial models.
**Default value:** `1000`
#### `REFINERY_SEMANTICS_WARMUP_TIMEOUT_MS`
Timeout for partial model semantics calculation in milliseconds when the server first start.
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).
**Default value:** equal to 2 × `REFINERY_SEMANTICS_TIMEOUT`
#### `REFINERY_MODEL_GENERATION_TIMEOUT_SEC`
Timeout for model generation in seconds.
: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.
: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.
**Default value:** `600` (10 minutes)
### Threading
:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation.
#### `REFINERY_XTEXT_THREAD_COUNT`
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.
:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation.
**Default value:** `1`
#### `REFINERY_XTEXT_LOCKING_THREAD_COUNT`
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.
**Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT`
#### `REFINERY_XTEXT_SEMANTICS_THREAD_COUNT`
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.
Must be at least as large as `REFINERY_XTEXT_THREAD_COUNT`.
:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation.
**Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT`
#### `REFINERY_MODEL_GENERATION_THREAD_COUNT`
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.
:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. Each model generation task may also demand a large amount of memory in addition to CPU time.
**Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT`
### Libraries
#### `REFINERY_LIBRARY_PATH`
Modules (`.refinery` files) in this directory or colon-separated list of directories will be exposed to user via Refinery's `import` mechanism.
: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.
:warning: Make sure you only expose files that you want to make public. It's best to expose a directory that contains nothing other that `.refinery` files to minimize potential information leaks.
**Default value:** _empty_ (no directories are exposed)
|
