diff options
Diffstat (limited to 'subprojects/docs/src/docs')
-rw-r--r-- | subprojects/docs/src/docs/docker.md | 175 | ||||
-rw-r--r-- | subprojects/docs/src/docs/index.md | 11 | ||||
-rw-r--r-- | subprojects/docs/src/docs/language/_category_.yml | 10 | ||||
-rw-r--r-- | subprojects/docs/src/docs/language/classes.md | 8 | ||||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/_category_.yml | 10 | ||||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/file-system.md | 9 |
6 files changed, 223 insertions, 0 deletions
diff --git a/subprojects/docs/src/docs/docker.md b/subprojects/docs/src/docs/docker.md new file mode 100644 index 00000000..c61c1457 --- /dev/null +++ b/subprojects/docs/src/docs/docker.md | |||
@@ -0,0 +1,175 @@ | |||
1 | --- | ||
2 | SPDX-FileCopyrightText: 2024 The Refinery Authors | ||
3 | SPDX-License-Identifier: EPL-2.0 | ||
4 | sidebar_position: 100 | ||
5 | sidebar_label: Docker | ||
6 | --- | ||
7 | |||
8 | # Running in Docker | ||
9 | |||
10 | :::note | ||
11 | |||
12 | Refinery can run as a cloud-based _Graph Solver as a Service_ without local installation. | ||
13 | If you're just looking to try Refinery, our [online demo](https://refinery.services/) provides a seamless experience without installation. | ||
14 | |||
15 | ::: | ||
16 | |||
17 | :::info | ||
18 | |||
19 | Installing Refinery as a Docker container can support more advanced use cases, such as when generating models with more resources or a longer timeout. | ||
20 | |||
21 | ::: | ||
22 | |||
23 | 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: | ||
24 | |||
25 | ```shell | ||
26 | docker run --rm -it -p 8888:8888 ghcr.io/graphs4value/refinery | ||
27 | ``` | ||
28 | |||
29 | Once Docker pulls and starts the container, you can navigate to http://localhost:8888 to open the model generation interface and start editing. | ||
30 | |||
31 | Alternatively, you can follow the [instructions to set up a local development environment](/api/contributing) and compile and run Refinery from source. | ||
32 | |||
33 | ## Updating | ||
34 | |||
35 | To take advantage of the latest updates, you can simply re-pull our Docker container from the GitHub Container Registry: | ||
36 | |||
37 | ```shell | ||
38 | docker pull ghcr.io/graphs4value/refinery | ||
39 | ``` | ||
40 | |||
41 | Restart the container to make sure that you're running the last pulled version. | ||
42 | |||
43 | ## Environmental variables | ||
44 | |||
45 | The Docker container supports the following environmental variables to customize its behavior. | ||
46 | Customizing these variable should only be needed if you want to _increase resource limits_ or _expose you Refinery instance over the network_ for others. | ||
47 | |||
48 | Notes for **local-only instances** are highlighted with the :arrow_right: arrow emoji. | ||
49 | |||
50 | Important security notices for **public instances** are highlighted with the :warning: warning emoji. | ||
51 | |||
52 | ### Networking | ||
53 | |||
54 | #### `REFINERY_LISTEN_HOST` | ||
55 | |||
56 | Hostname to listen at for incoming HTTP connections. | ||
57 | |||
58 | **Default value:** `0.0.0.0` (accepts connections on any IP address) | ||
59 | |||
60 | #### `REFINERY_LISTEN_PORT` | ||
61 | |||
62 | TCP port to listen at for incoming HTTP connections. | ||
63 | |||
64 | 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. | ||
65 | |||
66 | 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. | ||
67 | |||
68 | **Default value:** `8888` | ||
69 | |||
70 | #### `REFINERY_PUBLIC_HOST` | ||
71 | |||
72 | Publicly visible hostname of the Refinery instance. | ||
73 | |||
74 | :arrow_right: For installations only accessed locally (i.e., `localhost:8888`) without any reverse proxy, you can safely leave this empty. | ||
75 | |||
76 | :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/). | ||
77 | |||
78 | **Default value:** _empty_ | ||
79 | |||
80 | #### `REFINERY_PUBLIC_PORT` | ||
81 | |||
82 | Publicly visible port of the Refinery instance. | ||
83 | |||
84 | :arrow_right: For installations only accessed locally (i.e., `localhost:8888`), this value is ignored because `REFINERY_PUBLC_HOST` is not set. | ||
85 | |||
86 | **Default value:** `443` | ||
87 | |||
88 | #### `REFINERY_ALLOWED_ORIGINS` | ||
89 | |||
90 | Comma-separated list of allowed origins for incoming WebSocket connections. If this variable is empty, all incoming WebSocket connections are accepted. | ||
91 | |||
92 | :arrow_right: For installations only accessed locally (i.e., `localhost:8888`) without any reverse proxy, you can safely leave this empty. | ||
93 | |||
94 | :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. | ||
95 | |||
96 | **Default value:** equal to `REFINERY_PUBLIC_HOST:REFINERY_PUBLIC_PORT` if they are both set, _empty_ otherwise | ||
97 | |||
98 | ### Timeouts | ||
99 | |||
100 | #### `REFINERY_SEMANTICS_TIMEOUT_MS` | ||
101 | |||
102 | Timeout for partial model semantics calculation in milliseconds. | ||
103 | |||
104 | :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. | ||
105 | |||
106 | :warning: Increasing this timeout may increase server load. Excessively large timeout may allow users to overload you server by entering extremely complex partial models. | ||
107 | |||
108 | **Default value:** `1000` | ||
109 | |||
110 | #### `REFINERY_SEMANTICS_WARMUP_TIMEOUT_MS` | ||
111 | |||
112 | Timeout for partial model semantics calculation in milliseconds when the server first start. | ||
113 | |||
114 | 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). | ||
115 | |||
116 | **Default value:** equal to 2 × `REFINERY_SEMANTICS_TIMEOUT` | ||
117 | |||
118 | #### `REFINERY_MODEL_GENERATION_TIMEOUT_SEC` | ||
119 | |||
120 | Timeout for model generation in seconds. | ||
121 | |||
122 | :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. | ||
123 | |||
124 | :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. | ||
125 | |||
126 | **Default value:** `600` (10 minutes) | ||
127 | |||
128 | ### Threading | ||
129 | |||
130 | :warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. | ||
131 | |||
132 | #### `REFINERY_XTEXT_THREAD_COUNT` | ||
133 | |||
134 | 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. | ||
135 | |||
136 | :warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. | ||
137 | |||
138 | **Default value:** `1` | ||
139 | |||
140 | #### `REFINERY_XTEXT_LOCKING_THREAD_COUNT` | ||
141 | |||
142 | 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. | ||
143 | |||
144 | |||
145 | **Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` | ||
146 | |||
147 | #### `REFINERY_XTEXT_SEMANTICS_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 | Must be at least as large as `REFINERY_XTEXT_THREAD_COUNT`. | ||
152 | |||
153 | :warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. | ||
154 | |||
155 | **Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` | ||
156 | |||
157 | #### `REFINERY_MODEL_GENERATION_THREAD_COUNT` | ||
158 | |||
159 | 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. | ||
160 | |||
161 | :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. | ||
162 | |||
163 | **Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` | ||
164 | |||
165 | ### Libraries | ||
166 | |||
167 | #### `REFINERY_LIBRARY_PATH` | ||
168 | |||
169 | Modules (`.refinery` files) in this directory or colon-separated list of directories will be exposed to user via Refinery's `import` mechanism. | ||
170 | |||
171 | :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. | ||
172 | |||
173 | :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. | ||
174 | |||
175 | **Default value:** _empty_ (no directories are exposed) | ||
diff --git a/subprojects/docs/src/docs/index.md b/subprojects/docs/src/docs/index.md new file mode 100644 index 00000000..bb28df57 --- /dev/null +++ b/subprojects/docs/src/docs/index.md | |||
@@ -0,0 +1,11 @@ | |||
1 | --- | ||
2 | SPDX-FileCopyrightText: 2024 The Refinery Authors | ||
3 | SPDX-License-Identifier: EPL-2.0 | ||
4 | sidebar_position: 0 | ||
5 | --- | ||
6 | |||
7 | # Introduction | ||
8 | |||
9 | Various software and systems engineering scenarios rely on the systematic construction of consistent graph models. However, **automatically generating a diverse set of consistent graph models** for complex domain specifications is challenging. First, the graph generation problem must be specified with mathematical precision. Moreover, graph generation is a computationally complex task, which necessitates specialized logic solvers. | ||
10 | |||
11 | **Refinery is a novel open-source software framework** to automatically synthesize a diverse set of consistent domain-specific graph models. The framework offers an expressive high-level specification language using partial models to succinctly formulate a wide range of graph generation challenges. It also provides a modern cloud-based architecture for a scalable _Graph Solver as a Service,_ which uses logic reasoning rules to efficiently synthesize a diverse set of solutions to graph generation problems by partial model refinement. Applications include system-level architecture synthesis, test generation for modeling tools or traffic scenario synthesis for autonomous vehicles. | ||
diff --git a/subprojects/docs/src/docs/language/_category_.yml b/subprojects/docs/src/docs/language/_category_.yml new file mode 100644 index 00000000..7060edf3 --- /dev/null +++ b/subprojects/docs/src/docs/language/_category_.yml | |||
@@ -0,0 +1,10 @@ | |||
1 | # SPDX-FileCopyrightText: 2024 The Refinery Authors | ||
2 | # | ||
3 | # SPDX-License-Identifier: EPL-2.0 | ||
4 | |||
5 | position: 2 | ||
6 | label: Language reference | ||
7 | link: | ||
8 | type: generated-index | ||
9 | slug: /category/language | ||
10 | description: Learn more about the Refinery partial modeling language! | ||
diff --git a/subprojects/docs/src/docs/language/classes.md b/subprojects/docs/src/docs/language/classes.md new file mode 100644 index 00000000..aa569870 --- /dev/null +++ b/subprojects/docs/src/docs/language/classes.md | |||
@@ -0,0 +1,8 @@ | |||
1 | --- | ||
2 | SPDX-FileCopyrightText: 2024 The Refinery Authors | ||
3 | SPDX-License-Identifier: EPL-2.0 | ||
4 | description: Metamodeling in Refinery | ||
5 | sidebar_position: 0 | ||
6 | --- | ||
7 | |||
8 | # Classes and references | ||
diff --git a/subprojects/docs/src/docs/tutorials/_category_.yml b/subprojects/docs/src/docs/tutorials/_category_.yml new file mode 100644 index 00000000..25a06d98 --- /dev/null +++ b/subprojects/docs/src/docs/tutorials/_category_.yml | |||
@@ -0,0 +1,10 @@ | |||
1 | # SPDX-FileCopyrightText: 2024 The Refinery Authors | ||
2 | # | ||
3 | # SPDX-License-Identifier: EPL-2.0 | ||
4 | |||
5 | position: 1 | ||
6 | label: Tutorials | ||
7 | link: | ||
8 | type: generated-index | ||
9 | title: Tutorial overview | ||
10 | description: Try Refinery in practical partial modeling challenges! | ||
diff --git a/subprojects/docs/src/docs/tutorials/file-system.md b/subprojects/docs/src/docs/tutorials/file-system.md new file mode 100644 index 00000000..aed1cd87 --- /dev/null +++ b/subprojects/docs/src/docs/tutorials/file-system.md | |||
@@ -0,0 +1,9 @@ | |||
1 | --- | ||
2 | SPDX-FileCopyrightText: 2023-2024 The Refinery Authors | ||
3 | SPDX-License-Identifier: EPL-2.0 | ||
4 | description: Introduction to classes, references, and error predicates | ||
5 | sidebar_position: 0 | ||
6 | sidebar_label: File system | ||
7 | --- | ||
8 | |||
9 | # File system tutorial | ||