Skip to content

Commit f329ae1

Browse files
LEDfanLEDfan
committed
Move docs to website
1 parent b9a01fe commit f329ae1

3 files changed

Lines changed: 13 additions & 653 deletions

File tree

‎README.md‎

Lines changed: 10 additions & 157 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,25 @@
11
# ShinyProxy Operator
22

3-
Easily run ShinyProxy on a Kubernetes cluster
3+
Easily run ShinyProxy on a Docker host or on a Kubernetes cluster.
44

5-
**(c) Copyright Open Analytics NV, 2020-2024 - Apache License 2.0**
5+
**(c) Copyright Open Analytics NV, 2020-2025 - Apache License 2.0**
66

77
## Why?
88

9-
Deploying and managing ShinyProxy can get complex when many apps are used,
10-
especially when the configuration of ShinyProxy is often updated.
9+
See the [Features](https://shinyproxy.io/documentation/shinyproxy-operator/features/)
10+
page in the documentation to understand why this is so great.
1111

12-
When restarting a running ShinyProxy instance (in order to update its
13-
configuration), users will face a disconnect from their running applications.
14-
The only solution to guarantee that users do not lose their connection to
15-
running apps, is to keep the current instance alive when updating ShinyProxy's
16-
configuration. However, manually keeping track of these instances would be too
17-
cumbersome and should therefore be automated.
12+
## Docs
1813

19-
The ShinyProxy operator for Kubernetes is able to manage multiple ShinyProxy
20-
instances and their configuration.
14+
See the [website](https://shinyproxy.io/documentation/shinyproxy-operator/kubernetes/) for all documentation.
2115

22-
### Example
16+
## Support
2317

24-
Assume we have some ShinyProxy configuration `config1` which contains one app
25-
called `app1`. When the operator starts working, it checks whether a ShinyProxy
26-
instance exists with that configuration. If not, it starts a ShinyProxy instance
27-
and all other required configuration. Users can now start using `app1` on this
28-
instance.
18+
See the [website](https://shinyproxy.io/support/) on how to get support.
2919

30-
Some time later, the need for a second app arises. Therefore, the administrator
31-
adapts the configuration of ShinyProxy to include a second app `app2`.
20+
## Announcements
3221

33-
However, some users are still using `app1` on the old instance. These apps may
34-
have some state, which should not be lost. Therefore, the operator starts a
35-
second ShinyProxy instance using configuration `config2`. The operator does not
36-
modify the original ShinyProxy server, therefore the existing apps continue to
37-
work (even if they are using Websocket connections).
38-
39-
All new HTTP (and Websocket) connections are forwarded to the new server, i.e.
40-
any new connection is handled by the new server. Therefore, if users go to the
41-
main ShinyProxy page, they will see that a new app is available. Every user (
42-
also those still using the old application) can start the new app. The operator
43-
stops and removes the old server as soon as it has finished handling any
44-
existing (Websocket) connections.
22+
Subscribe on the [community forum](https://support.openanalytics.eu/c/shinyproxy/shinyproxy-announcements/10) for announcements of new releases and features.
4523

4624
## Building from source
4725

@@ -54,131 +32,6 @@ mvn -U clean install
5432
The build will result in a single `.jar` file:
5533
`target/target/shinyproxy-operator-jar-with-dependencies.jar`.
5634

57-
## Running
58-
59-
The operator should be run in Kubernetes using
60-
the [docker image](https://hub.docker.com/r/openanalytics/shinyproxy-operator).
61-
It can run in either `clustered` or `namespaced` mode. In the former the
62-
operator looks for ShinyProxy instances in all namespaces while in the latter it
63-
only manages ShinyProxy instances in its own namespace.
64-
65-
See the [docs/deployment](docs/deployment) folder for more information.
66-
67-
## Configuration
68-
69-
We try to keep the configuration of the Operator itself as minimum as possible.
70-
Furthermore, we want the operator to work without configuration in most cases.
71-
Nevertheless, for some specific cases some configuration options are available.
72-
For now these options are specified using environment variables. All variables
73-
start with the `SPO` prefix, meaning **S**hiny**P**roxy**O**perator.
74-
75-
- `SPO_MODE`: can either be `namespaced` or `clustered` (default). This
76-
specifies whether the operator should only look in its own namespace for
77-
ShinyProxy configurations or in all namespaces.
78-
- `SPO_PROBE_INITIAL_DELAY`: specifies the initial delay of the Readiness and
79-
Liveness probes. This is useful when the used Kubernetes version does not
80-
support startup probes.
81-
- `SPO_PROBE_FAILURE_THRESHOLD`: specifies the failure threshold of the
82-
Readiness and Liveness probes. This is useful when the used Kubernetes version
83-
does not support startup probes.
84-
- `SPO_PROBE_TIMEOUT`: specifies the timeout in seconds of the Readiness and
85-
Liveness probes. This is useful when the used Kubernetes version does not
86-
support startup probes.
87-
- `SPO_STARTUP_PROBE_INITIAL_DELAY`: specifies the initial delay of the StartUp
88-
probe. By default, this is 60 seconds.
89-
- `SPO_LOG_LEVEL`: configures the log level of the operator, may be one of the
90-
following:
91-
- `OFF`: disables logging
92-
- `ERROR`
93-
- `WARN`
94-
- `INFO`
95-
- `DEBUG`: default (may change)
96-
- `TRACE`
97-
- `ALL`: enables all logging
98-
99-
Note: in our deployments where startup probes aren't supported we have success
100-
with the following configuration:
101-
102-
- `SPO_PROBE_INITIAL_DELAY` to something between 40 and 140 depending on the
103-
performance of the cluster.
104-
- `SPO_PROBE_FAILURE_THRESHOLD` to `2`
105-
- `SPO_PROBE_TIMEOUT` to `3`
106-
107-
## Supported Versions
108-
109-
The first stable release of the operator (1.0.0) is compatible with ShinyProxy
110-
2.6.0. Older ShinyProxy versions are supported by running development snapshots
111-
of the operator, however, we strongly advice to upgrade to the latest version of
112-
ShinyProxy and the operator for the best experience.
113-
114-
| ShinyProxy Version | Minimum operator version | Maximum operator version (inclusive) |
115-
|--------------------|----------------------------------|--------------------------------------|
116-
| 3.1.0 | 2.1.0 | TBD |
117-
| 3.0.0 | 2.0.0 | TBD (works with 2.1.0) |
118-
| 2.6.0 | 1.0.0 | 1.1.0 |
119-
| 2.5.0 | `0.0.1-SNAPSHOT-20210302.095930` | `0.0.1-SNAPSHOT-20210607.070151` |
120-
| 2.4.3 | `0.0.1-SNAPSHOT-20201215.112635` | `0.0.1-SNAPSHOT-20201215.112635` |
121-
122-
## Kubernetes versions
123-
124-
| | k8s 1.29.x | k8s 1.28.x | k8s 1.27.x | k8s 1.26.x | k8s 1.25.x | k8s 1.24.x | k8s 1.23.x | k8s 1.22.x | k8s >= v1.21.3 | k8s >= 1.20.10 | v1.19 | <= v1.18 |
125-
|-------|------------|------------|------------|------------|------------|------------|------------|------------|----------------|----------------|-------|----------|
126-
| 2.1.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
127-
| 2.0.0 | ✓¹ | ✓¹ | ✓¹ | ✓¹ | ✓¹ | ✓¹ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
128-
129-
**Note:**
130-
131-
- ¹ version 2.0.0 supports these Kubernetes versions, but might stop syncing
132-
after some time, this issue is solved in version 2.1.0
133-
134-
### Update to 2.0.0
135-
136-
Be aware of these changes when updating to version 2.0.0:
137-
138-
- the old mechanism where cookies were used to assign users to specific
139-
ShinyProxy servers is no longer used. Instead, as soon as a new server is
140-
started, all new requests will be handled by the new server, including
141-
requests for existing apps. Only existing websocket connections will stay open
142-
on the old servers. This has multiple benefits:
143-
- when a new server is started, users will immediately use and see the
144-
configuration of that new server. In other words, if a new configuration
145-
includes a new app, this app is immediately available to all users (even
146-
if they are using apps started on older servers)
147-
- there is no longer a process of transferring users to new servers. Both
148-
the forced method and the manual method (where users have to click a
149-
button) are removed. Users will immediately use the new configuration.
150-
- apps can be run for a (very) long time, even if frequently updating the
151-
configuration and without having many old servers. Old servers are removed
152-
as soon as no websocket connections are running on that server.
153-
- Skipper is no longer a dependency of the operator. There is no benefit in
154-
using with version two of the operator.
155-
- the operator now requires ShinyProxy to store the active proxies in Redis.
156-
Therefore, since this release Redis takes a more critical role. When running
157-
Redis inside Kubernetes, it is therefore best practice to use Redis Sentinel.
158-
This way Redis runs in a High Available mode, using three replicas. Compared
159-
to running a single Redis server, this prevents a single point of failure on
160-
Redis and the node it is running on. This repository contains all manifests
161-
required to set up Redis Sentinel (based on the bitnamai Redis helm chart).
162-
163-
The best way to update to ShinyProxy 2.0.0 is by creating a fresh deployment of
164-
the operator and migrating users to this new deployment. The following changes
165-
need to be made to the ShinyProxy configuration file:
166-
167-
- add the property `proxy.store-mode: Redis`
168-
- add the property `proxy.stop-proxies-on-shutdown: false`
169-
- optionally add the
170-
property [`kubernetesIngressPatches`](docs/deployment#modify-the-ingress-resource)
171-
in order to customize the ingress created by the operator.
172-
- update the ShinyProxy image to `openanalytics/shinyproxy:3.1.1`
173-
174-
### Update to 2.1.0
175-
176-
The [ShinyProxy CRD](docs/deployment/bases/namespaced/crds/shinyproxy.crd.yaml)
177-
has been updated in version 2.1.0, it is important to update the CRD in your
178-
cluster. Running the [deployment commands](docs/deployment/) is enough. The CRD
179-
can be updated while ShinyProxy and the ShinyProxy operator are running in the
180-
cluster.
181-
18235
## Java Version
18336

18437
This project requires JDK 17.

‎docs/README.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
11
# Docs
22

3-
- [Deployment (with examples)](deployment/)
4-
- [Prometheus monitoring](prometheus.md)
3+
The documentation has been moved to the [website](https://shinyproxy.io/documentation/shinyproxy-operator/kubernetes/).

0 commit comments

Comments
 (0)