Skip to content

Commit d430c0a

Browse files
amrit3701amrit3701
authored
Merge pull request #46 from amrit3701/feat/integration_with_truenas
 Feature: Installing LENS on TrueNAS SCALE using Custom App Install via YAML
2 parents bbce737 + 3981832 commit d430c0a

File tree

2 files changed

+368
-0
lines changed

2 files changed

+368
-0
lines changed

‎docs/lens-truenas-app.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
<!--
2+
SPDX-FileCopyrightText: 2025 Amritpal Singh <[email protected]>
3+
4+
SPDX-License-Identifier: AGPL-3.0-or-later
5+
-->
6+
7+
# Lens App Installation Guide for TrueNAS SCALE
8+
9+
This guide provides step-by-step instructions for installing Lens on TrueNAS SCALE using Custom App Install via YAML.
10+
11+
## Table of Contents
12+
13+
- [Overview](#overview)
14+
- [Prerequisites](#prerequisites)
15+
- [Storage Setup](#storage-setup)
16+
- [Installation Steps](#installation-steps)
17+
- [Configuration](#configuration)
18+
- [Accessing Services](#accessing-services)
19+
20+
## Overview
21+
22+
The Lens App deploys a complete Lens stack on TrueNAS SCALE, including:
23+
24+
- **Backend API** - Main application server (port 30305)
25+
- **Frontend** - Web interface (port 30306)
26+
- **MongoDB** - Database (port 27018)
27+
- **Redis** - Cache and message broker for workers
28+
- **FC Worker API** - FreeCAD worker API
29+
- **FC Worker Celery** - Background task processor
30+
31+
## Prerequisites
32+
33+
Before installing, ensure you have:
34+
35+
1. **TrueNAS SCALE** with Apps enabled
36+
2. **Storage pool** available for persistent data
37+
3. **Network access** to the TrueNAS host
38+
39+
## Storage Setup
40+
41+
### Step 1: Determine Your Storage Path
42+
43+
You need to identify where to store persistent data. Common options:
44+
45+
- **Apps pool** (recommended): `/mnt/[pool-name]/ix-applications/lens/...`
46+
- Find your Apps pool in: **Apps > Settings > Advanced Settings > Pool**
47+
- **Custom dataset**: `/mnt/[pool-name]/[dataset-name]/lens/...`
48+
49+
### Step 2: Create Required Directories
50+
51+
Open the TrueNAS Shell (System Settings > Shell) or SSH into your TrueNAS host:
52+
53+
```bash
54+
# Replace /mnt/[your-pool] with your actual Apps pool path
55+
# Example: /mnt/tank/ix-applications/lens
56+
57+
# Create MongoDB data directory
58+
mkdir -p /mnt/[your-pool]/ix-applications/lens/mongodb_data
59+
60+
# Create uploads directory
61+
mkdir -p /mnt/[your-pool]/ix-applications/lens/uploads_data
62+
63+
# Set MongoDB directory ownership (MongoDB runs as user 568:568)
64+
chown -R 568:568 /mnt/[your-pool]/ix-applications/lens/mongodb_data
65+
```
66+
67+
### Step 3: Verify Directory Permissions
68+
69+
```bash
70+
# Check MongoDB directory
71+
ls -la /mnt/[your-pool]/ix-applications/lens/mongodb_data
72+
73+
# Check uploads directory
74+
ls -la /mnt/[your-pool]/ix-applications/lens/uploads_data
75+
```
76+
77+
## Installation Steps
78+
79+
### Step 1: Open Custom App YAML Editor
80+
81+
1. Log in to your TrueNAS SCALE web interface
82+
2. Navigate to **Apps > Discover Apps**
83+
3. Click the **three-dot menu (⋮)** next to **Custom App**
84+
4. Select **Install via YAML** from the menu
85+
5. A YAML editor will open
86+
87+
### Step 2: Paste Configuration
88+
89+
1. Copy the contents of `lens-truenas-app.yaml`
90+
2. Paste it into the YAML editor
91+
3. **Important**: Before proceeding, you must update the configuration (see [Configuration](#configuration) below)
92+
93+
### Step 3: Update Configuration
94+
95+
Before deploying, update the following in the YAML:
96+
97+
#### Storage Paths
98+
99+
Replace all instances of `/mnt/[your-pool]/ix-applications/lens` with your actual storage path:
100+
101+
```yaml
102+
volumes:
103+
- /mnt/[your-pool]/ix-applications/lens/mongodb_data:/data/db
104+
- /mnt/[your-pool]/ix-applications/lens/uploads_data:/app/uploads
105+
```
106+
107+
#### Network Configuration
108+
109+
Update the `HOSTNAME`, `FRONTEND_URL`, and `VITE_APP_API_URL` environment variables:
110+
111+
```yaml
112+
environment:
113+
- HOSTNAME=192.168.1.100 # Replace with your TrueNAS IP or hostname
114+
- FRONTEND_URL=http://192.168.1.100:30306 # Update accordingly
115+
- VITE_APP_API_URL=http://192.168.1.100:30305/ # Backend API URL (used by both frontend and backend)
116+
```
117+
118+
#### Admin Credentials
119+
120+
**⚠️ SECURITY WARNING**: Change the default admin credentials before deploying:
121+
122+
```yaml
123+
environment:
124+
- [email protected] # Change this
125+
- DEFAULT_ADMIN_USERNAME=admin # Change this
126+
- [email protected] # Change this
127+
- DEFAULT_ADMIN_NAME=Administrator
128+
```
129+
130+
#### SMTP Configuration (Optional)
131+
132+
If you want email functionality, configure SMTP:
133+
134+
```yaml
135+
environment:
136+
- SMTP_HOST=smtp.example.com
137+
- SMTP_PORT=465
138+
- [email protected]
139+
- SMTP_PASS=your-password
140+
- [email protected]
141+
```
142+
143+
#### Port Configuration
144+
145+
Adjust ports if they conflict with other services:
146+
147+
- Backend: `30305:30305` (change this port if needed)
148+
- Frontend: `30306:80` (change first number if needed)
149+
- MongoDB: `27018:27017` (change first number if needed)
150+
151+
### Step 4: Deploy
152+
153+
1. Review all configuration changes
154+
2. Click **Save** to deploy the application
155+
3. TrueNAS will start pulling images and creating containers
156+
157+
### Step 5: Monitor Deployment
158+
159+
1. Navigate to **Apps**
160+
2. You will see all running instances listed
161+
3. Check the status of your Lens app
162+
4. Select the Lens app to view the status of all Lens services:
163+
- Wait for all services to show "Running" status
164+
- Check logs if any service fails to start
165+
166+
## Configuration
167+
168+
### Environment Variables Reference
169+
170+
#### Backend Service
171+
172+
| Variable | Description | Required | Default |
173+
|----------|-------------|----------|---------|
174+
| `HOSTNAME` | Server hostname or IP | Yes | - |
175+
| `PORT` | Backend API port | No | 30305 |
176+
| `FRONTEND_URL` | Frontend application URL | Yes | - |
177+
| `VITE_APP_API_URL` | Backend API URL (used by both frontend and backend) | Yes | - |
178+
| `SMTP_HOST` | SMTP server hostname | No | - |
179+
| `SMTP_PORT` | SMTP server port | No | 465 |
180+
| `SMTP_USER` | SMTP username | No | - |
181+
| `SMTP_PASS` | SMTP password | No | - |
182+
| `SMTP_FROM` | SMTP from address | No | - |
183+
| `DEFAULT_ADMIN_EMAIL` | Initial admin email | Yes | - |
184+
| `DEFAULT_ADMIN_USERNAME` | Initial admin username | Yes | - |
185+
| `DEFAULT_ADMIN_PASSWORD` | Initial admin password | Yes | - |
186+
| `DEFAULT_ADMIN_NAME` | Initial admin display name | Yes | - |
187+
188+
#### Frontend Service
189+
190+
| Variable | Description | Required | Default |
191+
|----------|-------------|----------|---------|
192+
| `VITE_APP_API_URL` | Backend API URL | Yes | - |
193+
| `VITE_STRIPE_PURCHASE_PEER_URL` | Stripe purchase URL | No | - |
194+
| `PROXY_SCHEME_PREFIX` | Proxy scheme prefix | No | `http://` |
195+
196+
### Volume Mounts
197+
198+
| Service | Host Path | Container Path | Purpose |
199+
|---------|-----------|----------------|---------|
200+
| MongoDB | `/mnt/[pool]/.../mongodb_data` | `/data/db` | Database files |
201+
| Backend | `/mnt/[pool]/.../uploads_data` | `/app/uploads` | User uploads |
202+
| Init Container | `/mnt/[pool]/.../uploads_data` | `/mnt/uploads` | Initial file copy |
203+
204+
## Accessing Services
205+
206+
- **Frontend**: `http://[HOSTNAME]:30306`
207+
- **Backend API**: `http://[HOSTNAME]:30305`
208+
- **MongoDB** (external): `mongodb://[HOSTNAME]:27018`

‎lens-truenas-app.yaml‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# SPDX-FileCopyrightText: 2025 Amritpal Singh <[email protected]>
2+
#
3+
# SPDX-License-Identifier: AGPL-3.0-or-later
4+
5+
services:
6+
lens-init:
7+
image: amrit3701/lens:backend-latest
8+
container_name: lens-init
9+
user: "0:0"
10+
volumes:
11+
- /mnt/[your-pool]/ix-applications/lens/uploads_data:/mnt/uploads
12+
entrypoint: ["/bin/sh", "-c"]
13+
command:
14+
- |
15+
set -e
16+
echo "Initializing uploads directory..."
17+
if [ -z "$(ls -A /mnt/uploads 2>/dev/null)" ] && [ -d /app/uploads ]; then
18+
echo "Copying sample files from image to volume..."
19+
cp -r /app/uploads/* /mnt/uploads/ 2>/dev/null || true
20+
echo "Sample files copied successfully"
21+
else
22+
echo "Uploads directory already contains files, skipping copy"
23+
fi
24+
echo "Uploads directory initialized"
25+
restart: on-failure
26+
network_mode: "none"
27+
28+
mongodb:
29+
image: mongo:latest
30+
container_name: lens-mongodb
31+
restart: unless-stopped
32+
user: "568:568"
33+
volumes:
34+
- /mnt/[your-pool]/ix-applications/lens/mongodb_data:/data/db
35+
ports:
36+
- 27018:27017
37+
healthcheck:
38+
test: ["CMD", "mongosh", "--host", "127.0.0.1", "--port", "27017", "backend-db", "--eval", "db.adminCommand('ping')", "--quiet"]
39+
interval: 30s
40+
timeout: 5s
41+
retries: 5
42+
start_period: 15s
43+
44+
backend:
45+
image: amrit3701/lens:backend-latest
46+
container_name: lens-backend
47+
restart: unless-stopped
48+
user: "0:0"
49+
environment:
50+
- HOSTNAME=192.168.1.100
51+
- PORT=30305
52+
- DB_URL=mongodb://mongodb:27017/backend-db
53+
- FRONTEND_URL=http://192.168.1.100:30306
54+
- VITE_APP_API_URL=http://192.168.1.100:30305/
55+
- FC_WORKER_URL=http://0.0.0.0:8080/2015-03-31/functions/function/invocations
56+
- SMTP_HOST=
57+
- SMTP_PORT=465
58+
- SMTP_USER=
59+
- SMTP_PASS=
60+
- SMTP_FROM=
61+
- [email protected]
62+
- DEFAULT_ADMIN_USERNAME=admin
63+
- [email protected]
64+
- DEFAULT_ADMIN_NAME=Administrator
65+
- LOCAL_SIGNED_URL_SECRET=
66+
volumes:
67+
- /mnt/[your-pool]/ix-applications/lens/uploads_data:/app/uploads
68+
ports:
69+
- 30305:30305
70+
depends_on:
71+
lens-init:
72+
condition: service_completed_successfully
73+
mongodb:
74+
condition: service_healthy
75+
healthcheck:
76+
test: ["CMD", "wget", "--quiet", "--spider", "http://127.0.0.1:30305/"]
77+
interval: 30s
78+
timeout: 5s
79+
retries: 5
80+
start_period: 15s
81+
82+
frontend:
83+
image: amrit3701/lens:frontend-latest
84+
container_name: lens-frontend
85+
restart: unless-stopped
86+
user: "0:0"
87+
cap_add:
88+
- CHOWN
89+
- SETUID
90+
- SETGID
91+
environment:
92+
- VITE_APP_API_URL=http://192.168.1.100:30305/
93+
- VITE_STRIPE_PURCHASE_PEER_URL=
94+
- PROXY_SCHEME_PREFIX=http://
95+
ports:
96+
- 30306:80
97+
depends_on:
98+
backend:
99+
condition: service_healthy
100+
healthcheck:
101+
test: ["CMD-SHELL", "/bin/bash -c '{ printf \"GET / HTTP/1.1\\r\\nHost: 127.0.0.1\\r\\nConnection: close\\r\\n\\r\\n\" >&0; grep \"HTTP\" | grep -q \"200\"; } 0<>/dev/tcp/127.0.0.1/80'"]
102+
interval: 30s
103+
timeout: 5s
104+
retries: 5
105+
start_period: 15s
106+
107+
fc-worker-redis:
108+
image: redis:alpine
109+
container_name: lens-fc-worker-redis
110+
restart: unless-stopped
111+
user: "0:0"
112+
healthcheck:
113+
test: ["CMD", "redis-cli", "-h", "127.0.0.1", "-p", "6379", "ping"]
114+
interval: 30s
115+
timeout: 5s
116+
retries: 5
117+
start_period: 15s
118+
119+
fc-worker-api:
120+
image: amrit3701/lens:fc-worker-api-latest
121+
container_name: lens-fc-worker-api
122+
restart: unless-stopped
123+
user: "0:0"
124+
network_mode: "service:backend"
125+
environment:
126+
- REDIS_HOST=fc-worker-redis
127+
- REDIS_PORT=6379
128+
depends_on:
129+
backend:
130+
condition: service_healthy
131+
fc-worker-redis:
132+
condition: service_healthy
133+
healthcheck:
134+
test: ["CMD-SHELL", "echo OK"]
135+
interval: 30s
136+
timeout: 5s
137+
retries: 5
138+
start_period: 15s
139+
140+
fc-worker-celery:
141+
image: amrit3701/lens:fc-worker-celery-latest
142+
container_name: lens-fc-worker-celery
143+
restart: unless-stopped
144+
user: "0:0"
145+
network_mode: "service:backend"
146+
environment:
147+
- REDIS_HOST=fc-worker-redis
148+
- REDIS_PORT=6379
149+
- BACKEND_URL=http://backend:30305
150+
depends_on:
151+
backend:
152+
condition: service_healthy
153+
fc-worker-redis:
154+
condition: service_healthy
155+
healthcheck:
156+
test: ["CMD-SHELL", "echo OK"]
157+
interval: 30s
158+
timeout: 5s
159+
retries: 5
160+
start_period: 15s

0 commit comments

Comments
 (0)