ClearDesk Support Portal

A Dockerized, consent-first remote-support portal for customers, technicians, and administrators. It provides branded help-request links, technician session tracking, audit logging, admin/user management, and a clean handoff into MeshCentral for remote desktop, terminal, and file support.

Remote-control capability is intentionally handled by MeshCentral rather than browser JavaScript. Modern browsers do not grant arbitrary operating-system mouse/keyboard control. The customer runs a native support agent and receives explicit consent prompts before privileged access.

Features

Customer

• Self-service Request Help form
• Unique, cryptographically random, expiring help links
• Explicit portal consent before the agent handoff
• OS-aware guidance for Windows, macOS, and Linux
• Clear session code, technician assignment, issue summary, and link-expiry information
• No silent or hidden remote-control startup

Technician

• Authenticated support dashboard
• Waiting / active / invited / resolved session states
• Claim and assign sessions
• Internal notes
• Session timestamps and customer consent status
• Per-session audit history
• One-click launch into the MeshCentral technician console
• Customer help-link rotation/revocation

Administrator

• Create secure help links
• Optional SMTP invitation delivery
• Create technician/admin accounts
• Enable/disable staff accounts
• CSS & Branding administration:
  • Portal/company name
  • Logo URL or fallback logo mark
  • Accent, hover, background, card, and text colors
  • Footer text
  • Up to 30 KB custom CSS
  • Live preview
  • Reset to defaults
• Recent audit-event view
• CSV audit export

Security / audit

• scrypt password hashing
• Random server-side auth tokens stored as SHA-256 hashes
• Random help-link tokens stored only as SHA-256 hashes
• SameSite auth cookies
• CSRF tokens for authenticated writes
• Login and public-endpoint rate limiting
• Helmet security headers
• Redacted HTTP logging (/help/<token> is logged as /help/:token)
• Persistent SQLite database with WAL mode
• Customer consent events recorded in the audit log
• MeshCentral is configured to require on-device user prompts for desktop, terminal, and file access
• MeshCentral desktop privacy bar enabled
• No auto-accept on prompt timeout, locked screen, or absent user

Architecture

Customer browser                       Technician browser
      |                                       |
      v                                       v
+-------------------+                 +-------------------+
| ClearDesk Portal  |                 | ClearDesk Portal  |
| :8080             |                 | Dashboard/Admin   |
|                   |                 +---------+---------+
| request + consent |                           |
| session tracking  |                           | Open console
| audit + branding  |                           v
+---------+---------+                 +-------------------+
          |                           | MeshCentral :8443 |
          | agent invitation          | remote desktop    |
          +-------------------------->| terminal / files  |
                                      +---------+---------+
                                                |
                                                v
                                      MeshAgent on customer
                                      Windows / macOS / Linux

The support workflow database and MeshCentral data are kept in separate persistent Docker volumes.

---

Quick Start — macOS + Docker Desktop

For the shortest version, see QUICKSTART.md.

1. Install Docker Desktop

Install Docker Desktop for Mac and make sure it is running.

2. Extract and start

Open Terminal in the extracted project folder:

cd ~/Downloads/support-portal
./scripts/quick-start-macos.sh

The script creates .env if it does not exist, generates a random portal admin password, builds the portal container, and starts MeshCentral.

Or do it manually:

cp .env.example .env
# Edit .env and replace ADMIN_PASSWORD with a strong password.
docker compose up -d --build

3. Open the services

• Support portal: http://localhost:8080
• MeshCentral: https://localhost:8443

The local MeshCentral TLS certificate is self-signed, so a browser certificate warning is expected during local development.

4. Create the first MeshCentral admin

Open https://localhost:8443 and create the first account. MeshCentral treats the first account on an empty domain as that domain's administrator.

Create a device group such as:

Support Sessions

Then create an Agent Invitation / public agent-install link for that group.

Copy that URL into .env:

REMOTE_AGENT_URL=https://localhost:8443/your-agent-invitation

Restart the portal:

docker compose restart support-portal

5. Sign in to the support portal

Use the portal admin credentials configured in .env:

ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your-password

Open:

http://localhost:8080/login

Go to Admin to create technicians, help links, invitations, and branding.

---

Test from another computer on your LAN

localhost only refers to the computer you are currently using. A Windows/Linux/Mac customer on another machine must use the Docker Mac's LAN address.

On the Mac running Docker:

./scripts/configure-lan-macos.sh

The helper:

1. Detects the Mac's LAN IPv4 address.
2. Updates the local MeshCentral certificate hostname.
3. Updates PUBLIC_BASE_URL and REMOTE_CONSOLE_URL in .env.
4. Recreates the Docker stack.

Example result:

Support portal: http://192.168.1.50:8080
MeshCentral:          https://192.168.1.50:8443

After changing to the LAN IP, recreate your MeshCentral Agent Invitation so the generated agent URL points to that LAN address instead of localhost.

The included local-development MeshCentral config uses:

"allowedOrigin": true

This prevents the common Invalid origin in HTTP request, click to reconnect problem when you alternate between localhost, 127.0.0.1, and your Mac's LAN IP.

Do not use that permissive origin configuration for a public Internet deployment. See the production section below.

---

Customer remote-support flow

Windows

1. Customer opens the unique /help/... link.
2. Customer reviews the session and checks the consent box.
3. Portal redirects to the configured MeshCentral Agent Invitation.
4. Customer downloads/runs the Windows support agent.
5. Customer approves UAC if elevation is required.
6. The device appears in the technician's MeshCentral device group.
7. Technician opens Desktop → Connect.
8. MeshCentral displays an on-device consent prompt.
9. Customer approves the prompt.
10. Remote desktop begins and the privacy bar remains visible.

macOS

1. Customer opens the help link and explicitly consents.
2. Customer downloads/runs the macOS agent.
3. In System Settings → Privacy & Security, allow the support agent under:
   • Screen & System Audio Recording (or Screen Recording on older releases)
   • Accessibility
4. Reopen/reconnect the agent if macOS asks for it.
5. Technician opens Desktop → Connect.
6. Customer approves the MeshCentral consent prompt.

Screen-recording permission allows the technician to see the display; Accessibility permission is normally required for keyboard/mouse control.

Linux

1. Customer opens the help link and consents.
2. Customer follows the Linux binary/install command supplied by the MeshCentral invitation.
3. Device appears in MeshCentral.
4. Technician can use the available Desktop, Terminal, and Files functions.

For remote graphical desktop, use an X11/Xorg session. Upstream MeshAgent does not currently provide equivalent full desktop control for Wayland-only sessions; terminal/files remain useful, or the user can switch to Xorg where the distribution provides it.

---

Admin CSS & Branding

Sign in as an administrator and open:

Admin → CSS & Branding

Branding is stored in the portal SQLite database and survives container rebuilds through the support-data Docker volume.

Custom CSS is served through /branding.css after the base stylesheet. The portal blocks several high-risk legacy/dynamic CSS forms such as @import, javascript: URLs, expression(), and behavior:.

A bad branding configuration can be reverted using Reset defaults.

---

Logging and session tracking

The portal tracks:

• Admin-created invitations
• Customer-created requests
• Invitation emails
• Help-link opens
• Customer remote-access consent
• Technician claims
• Waiting/active/resolved/cancelled state changes
• Internal note updates
• Help-link rotations
• Staff account creation / enable / disable events
• Authentication successes/failures/logouts
• Branding saves and resets

Admin users can download up to the latest 10,000 audit events from:

Admin → Export audit CSV

Container access logs are structured JSON and deliberately redact raw help tokens.

View logs:

docker compose logs -f

Portal only:

docker compose logs -f support-portal

MeshCentral only:

docker compose logs -f meshcentral

---

Docker commands

# Build/start
docker compose up -d --build

# Status
docker compose ps

# Restart
docker compose restart

# Stop, retaining persistent volumes
docker compose down

# Recreate after configuration changes
docker compose up -d --build --force-recreate

# Tail logs
docker compose logs -f

Avoid this unless you intentionally want to destroy all persistent application/MeshCentral data:

docker compose down -v

---

Environment variables

See .env.example for the complete list.

Important values:

APP_NAME=ClearDesk Support
PUBLIC_BASE_URL=http://localhost:8080
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=replace-with-a-long-random-password
COOKIE_SECURE=false
TRUST_PROXY=false
ALLOW_PUBLIC_REQUESTS=true
REMOTE_CONSOLE_URL=https://localhost:8443
REMOTE_AGENT_URL=

SMTP is optional. When configured, the Admin panel can send help invitations directly.

---

Persistence and backups

Docker Compose creates these named volumes:

• support-data — support portal SQLite database
• meshcentral-data — MeshCentral database, certificates, and server state
• meshcentral-files — MeshCentral file storage
• meshcentral-web — MeshCentral custom web assets
• meshcentral-backups — MeshCentral backups

Back up persistent volumes according to your organization's retention and recovery requirements.

---

Production deployment

The included Compose file is designed first for local/LAN evaluation. Before exposing it to the Internet:

1. Use real DNS names, for example:
   • support.example.com
   • remote.example.com
2. Put the portal and MeshCentral behind trusted HTTPS/TLS.
3. Set:

PUBLIC_BASE_URL=https://support.example.com
REMOTE_CONSOLE_URL=https://remote.example.com
COOKIE_SECURE=true
TRUST_PROXY=true

4. Replace the local MeshCentral configuration with a production configuration. An example is included at:

meshcentral/config.production.example.json

5. Change MeshCentral from permissive local origin handling:

"allowedOrigin": true

to an explicit hostname list:

"allowedOrigin": ["remote.example.com"]

6. Set MeshCentral settings.cert to the externally reachable remote hostname.
7. Recreate the MeshCentral device-group invitation after hostname changes.
8. Use named technician accounts; do not share admin credentials.
9. Enable MFA/SSO for MeshCentral technicians where appropriate.
10. Restrict direct service ports if a reverse proxy is fronting the containers.
11. Configure backups and an audit-retention policy.
12. Consider pinning MeshCentral to a tested image version/digest rather than following latest in production.

The official MeshCentral configuration schema is referenced directly by the included config files so settings can be checked against upstream definitions.

---

Project layout

support-portal/
├── .env.example
├── Dockerfile
├── docker-compose.yml
├── package.json
├── README.md
├── QUICKSTART.md
├── meshcentral/
│   ├── config.json
│   └── config.production.example.json
├── scripts/
│   ├── quick-start-macos.sh
│   └── configure-lan-macos.sh
├── public/
│   ├── app.css
│   └── app.js
├── src/
│   ├── db.js
│   └── server.js
└── views/
    ├── partials/
    └── *.ejs

Portal-only Docker run

If you already operate another MeshCentral server, you can run only the portal:

docker build -t cleardesk-support .
docker run -d --name cleardesk-support --restart unless-stopped \
  --env-file .env \
  -p 8080:3000 \
  -v cleardesk-support-data:/data \
  cleardesk-support

Set REMOTE_CONSOLE_URL and REMOTE_AGENT_URL to your existing remote-support environment.

License / upstream

This project integrates with MeshCentral as a separate container. Review the MeshCentral project and license for your deployment requirements. The support portal source in this package is provided as the application project you requested; add your organization's own license file before redistribution if needed.