Skip to content

Commit 5ec6f77

Browse files
ganga2166ganga2166
committed
docs: add helm chart documentation for companion uploader service
1 parent 3948348 commit 5ec6f77

1 file changed

Lines changed: 261 additions & 0 deletions

File tree

‎charts/companion/README.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# Companion Helm Chart
2+
3+
A Helm chart for Companion - The companion plugin can be used to upload files to Transloadit for all kinds of processing, such as transcoding video, resizing images, zipping/unzipping, and much more.
4+
5+
## Overview
6+
7+
Companion is a server integration for Uppy file uploader that handles the server-to-server communication between your server and file storage providers such as Google Drive, Dropbox, Instagram, Facebook, OneDrive and remote URLs. Companion is not a target to upload files to, but rather a proxy that handles OAuth and downloads files from third parties on your behalf, then uploads them to the final destination.
8+
9+
Key features:
10+
- **OAuth Integration**: Handles OAuth flows for various cloud storage providers
11+
- **File Processing**: Integrates with Transloadit for file processing capabilities
12+
- **Secure Uploads**: Provides secure server-to-server file transfers
13+
- **Multiple Providers**: Supports Dropbox, Google Drive, Instagram, Facebook, Box, OneDrive, Zoom, and more
14+
15+
## Prerequisites
16+
17+
- Kubernetes 1.19+
18+
- Helm 3.2.0+
19+
- Valid OAuth credentials for the cloud storage providers you want to use
20+
21+
## Installation
22+
23+
### Add Helm Repository
24+
25+
```bash
26+
helm repo add factly https://factly.github.io/helm-charts
27+
helm repo update
28+
```
29+
30+
### Install Chart
31+
32+
```bash
33+
# Install with default values
34+
helm install companion factly/companion
35+
36+
# Install with custom values
37+
helm install companion factly/companion -f values.yaml
38+
39+
# Install in specific namespace
40+
helm install companion factly/companion --namespace companion --create-namespace
41+
```
42+
43+
## Uninstallation
44+
45+
```bash
46+
helm uninstall companion
47+
```
48+
49+
## Configuration
50+
51+
The following table lists the configurable parameters and their default values.
52+
53+
### Global Parameters
54+
55+
| Parameter | Description | Default |
56+
|-----------|-------------|---------|
57+
| `nameOverride` | String to partially override companion.fullname | `companion` |
58+
| `fullnameOverride` | String to fully override companion.fullname | `companion` |
59+
| `namespaceOverride` | Override the deployment namespace | `""` |
60+
| `imagePullSecrets` | Global Docker registry secret names as an array | `[]` |
61+
62+
### Image Parameters
63+
64+
| Parameter | Description | Default |
65+
|-----------|-------------|---------|
66+
| `image.repository` | Companion image repository | `transloadit/companion` |
67+
| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
68+
| `image.tag` | Companion image tag (overrides the image tag whose default is the chart appVersion) | `""` |
69+
70+
### Deployment Parameters
71+
72+
| Parameter | Description | Default |
73+
|-----------|-------------|---------|
74+
| `replicaCount` | Number of Companion replicas | `1` |
75+
| `autoscaling.enabled` | Enable horizontal pod autoscaler | `false` |
76+
| `autoscaling.minReplicas` | Minimum number of replicas | `2` |
77+
| `autoscaling.maxReplicas` | Maximum number of replicas | `5` |
78+
| `autoscaling.targetCPUUtilizationPercentage` | Target CPU utilization percentage | `80` |
79+
| `autoscaling.targetMemoryUtilizationPercentage` | Target memory utilization percentage | `80` |
80+
81+
### Environment Variables
82+
83+
| Parameter | Description | Default |
84+
|-----------|-------------|---------|
85+
| `env` | Array of environment variables for Companion configuration | See values.yaml |
86+
87+
#### Required Environment Variables
88+
89+
| Environment Variable | Description | Default |
90+
|---------------------|-------------|---------|
91+
| `COMPANION_SECRET` | Long set of random characters for server session | `"CHANGE_ME"` |
92+
| `COMPANION_DOMAIN` | Your server domain | `"YOUR SERVER DOMAIN"` |
93+
| `COMPANION_DATADIR` | File path for temporary file storage | `"/"` |
94+
| `COMPANION_PROTOCOL` | Server protocol (http/https) | `"http"` |
95+
| `COMPANION_PORT` | Port on which to start the server | `"3020"` |
96+
| `COMPANION_SELF_ENDPOINT` | Should be same as your domain + path | `"THIS SHOULD BE SAME AS YOUR DOMAIN + PATH"` |
97+
98+
#### Optional Provider Configuration
99+
100+
The chart supports configuration for various cloud storage providers through environment variables:
101+
102+
- **AWS S3**: `COMPANION_AWS_KEY`, `COMPANION_AWS_SECRET`, `COMPANION_AWS_BUCKET`, `COMPANION_AWS_REGION`
103+
104+
### Service Parameters
105+
106+
| Parameter | Description | Default |
107+
|-----------|-------------|---------|
108+
| `service.type` | Kubernetes service type | `NodePort` |
109+
| `service.port` | Service port | `3020` |
110+
| `service.portName` | Service port name | `http` |
111+
| `service.annotations` | Service annotations | `{}` |
112+
| `service.labels` | Service labels | `{}` |
113+
114+
### ServiceAccount Parameters
115+
116+
| Parameter | Description | Default |
117+
|-----------|-------------|---------|
118+
| `serviceAccount.create` | Specifies whether a service account should be created | `false` |
119+
| `serviceAccount.annotations` | Annotations to add to the service account | `{}` |
120+
| `serviceAccount.labels` | Labels to add to the service account | `{}` |
121+
| `serviceAccount.name` | The name of the service account to use | `"companion"` |
122+
123+
### Ingress Parameters
124+
125+
| Parameter | Description | Default |
126+
|-----------|-------------|---------|
127+
| `ingress.enabled` | Enable ingress controller resource | `false` |
128+
| `ingress.annotations` | Ingress annotations | See values.yaml |
129+
| `ingress.hosts` | Ingress hostnames | `["change-to-your-domain.com", "www.change-to-your-domain.com"]` |
130+
| `ingress.paths` | Ingress paths | `["/"]` |
131+
| `ingress.extraPaths` | Extra ingress paths | `[]` |
132+
| `ingress.tls` | Ingress TLS configuration | See values.yaml |
133+
134+
### Monitoring Parameters
135+
136+
| Parameter | Description | Default |
137+
|-----------|-------------|---------|
138+
| `metrics.enabled` | Enable metrics collection | `false` |
139+
| `metrics.serviceMonitor.enabled` | Enable ServiceMonitor for Prometheus | `false` |
140+
| `metrics.serviceMonitor.selector` | ServiceMonitor selector | `{release: monitoring}` |
141+
| `metrics.serviceMonitor.labels` | ServiceMonitor labels | `{}` |
142+
| `metrics.serviceMonitor.interval` | Metrics scrape interval | `30s` |
143+
| `metrics.serviceMonitor.scheme` | Metrics scrape scheme | `http` |
144+
| `metrics.serviceMonitor.scrapeTimeout` | Metrics scrape timeout | `30s` |
145+
146+
### Health Check Parameters
147+
148+
| Parameter | Description | Default |
149+
|-----------|-------------|---------|
150+
| `readinessProbe.initialDelaySeconds` | Initial delay for readiness probe | `10` |
151+
| `readinessProbe.timeoutSeconds` | Timeout for readiness probe | `5` |
152+
| `readinessProbe.successThreshold` | Success threshold for readiness probe | `1` |
153+
| `readinessProbe.failureThreshold` | Failure threshold for readiness probe | `5` |
154+
| `readinessProbe.periodSeconds` | Period for readiness probe | `10` |
155+
| `livenessProbe.initialDelaySeconds` | Initial delay for liveness probe | `50` |
156+
| `livenessProbe.timeoutSeconds` | Timeout for liveness probe | `5` |
157+
| `livenessProbe.successThreshold` | Success threshold for liveness probe | `1` |
158+
| `livenessProbe.failureThreshold` | Failure threshold for liveness probe | `5` |
159+
| `livenessProbe.periodSeconds` | Period for liveness probe | `10` |
160+
161+
### Resource Parameters
162+
163+
| Parameter | Description | Default |
164+
|-----------|-------------|---------|
165+
| `resources` | CPU/Memory resource requests/limits | `{}` |
166+
| `nodeSelector` | Node labels for pod assignment | `{}` |
167+
| `tolerations` | Tolerations for pod assignment | `[]` |
168+
| `affinity` | Affinity settings for pod assignment | `{}` |
169+
| `podAnnotations` | Annotations to add to pods | `{}` |
170+
| `securityContext` | Security context for pods | `{}` |
171+
172+
## Examples
173+
174+
### Basic Installation with Custom Domain
175+
176+
```yaml
177+
# values.yaml
178+
env:
179+
- name: COMPANION_SECRET
180+
value: "your-super-secret-key-here"
181+
- name: COMPANION_DOMAIN
182+
value: "companion.yourdomain.com"
183+
- name: COMPANION_PROTOCOL
184+
value: "https"
185+
- name: COMPANION_SELF_ENDPOINT
186+
value: "https://companion.yourdomain.com"
187+
188+
ingress:
189+
enabled: true
190+
hosts:
191+
- companion.yourdomain.com
192+
tls:
193+
- secretName: companion-tls
194+
hosts:
195+
- companion.yourdomain.com
196+
```
197+
198+
### Installation with Google Drive Support
199+
200+
```yaml
201+
# values.yaml
202+
env:
203+
- name: COMPANION_SECRET
204+
value: "your-super-secret-key-here"
205+
- name: COMPANION_DOMAIN
206+
value: "companion.yourdomain.com"
207+
- name: COMPANION_GOOGLE_KEY
208+
value: "your-google-oauth-client-id"
209+
- name: COMPANION_GOOGLE_SECRET
210+
value: "your-google-oauth-client-secret"
211+
```
212+
213+
### Installation with AWS S3 Support
214+
215+
```yaml
216+
# values.yaml
217+
env:
218+
- name: COMPANION_AWS_KEY
219+
value: "your-aws-access-key"
220+
- name: COMPANION_AWS_SECRET
221+
value: "your-aws-secret-key"
222+
- name: COMPANION_AWS_BUCKET
223+
value: "your-s3-bucket-name"
224+
- name: COMPANION_AWS_REGION
225+
value: "us-east-1"
226+
```
227+
228+
## Security Considerations
229+
230+
1. **Secret Management**: Always change the default `COMPANION_SECRET` value and use a secure random string
231+
2. **OAuth Credentials**: Store OAuth credentials securely using Kubernetes secrets rather than plain text in values
232+
3. **Domain Configuration**: Ensure `COMPANION_DOMAIN` and `COMPANION_SELF_ENDPOINT` match your actual deployment URL
233+
4. **Client Origins**: Use `COMPANION_CLIENT_ORIGINS` to whitelist allowed client domains for security
234+
235+
## Troubleshooting
236+
237+
### Common Issues
238+
239+
1. **OAuth Redirect Mismatch**: Ensure your OAuth app redirect URLs match your Companion domain
240+
2. **CORS Issues**: Configure `COMPANION_CLIENT_ORIGINS` to include your frontend domain
241+
3. **File Upload Failures**: Check that `COMPANION_DATADIR` has sufficient disk space and proper permissions
242+
4. **Provider Authentication**: Verify OAuth credentials are correctly configured for each provider
243+
244+
### Logs
245+
246+
To view Companion logs:
247+
248+
```bash
249+
kubectl logs -f deployment/companion
250+
```
251+
252+
## Links
253+
254+
- [Companion Documentation](https://uppy.io/docs/companion/)
255+
- [Uppy File Uploader](https://uppy.io/)
256+
- [Transloadit](https://transloadit.com/)
257+
- [Source Code](https://github.com/transloadit/uppy/tree/main/packages/%40uppy/companion)
258+
259+
## License
260+
261+
This Helm chart is licensed under the MIT License.

0 commit comments

Comments
 (0)