Self-Hosting: Missing Documentation for Short URL Service Configuration

[ndesjardins-comact]

Summary

When self-hosting Plannotator, the "Create short link" feature fails with no clear guidance on how to set it up. The codebase has hardcoded defaults pointing to external SaaS services, and documentation is either missing or unclear about:

1. How to configure the paste service for self-hosted setups
2. What environment variables need to be set and where
3. How to override default URLs in the compiled frontend
4. How CORS configuration works for the paste service

Problem Description

A user attempting to self-host Plannotator encountered:

• Portal showing "(Short URL service unavailable)" error when trying to create short links
• Browser console error: TypeError: Cannot read properties of undefined (reading 'generatorKey')
• Confusion about whether the paste service was running or if the frontend was misconfigured
• No documentation explaining how to wire up the internal paste service for self-hosted deployments

What Happened

The hardcoded defaults in packages/ui/utils/sharing.ts point to:

const DEFAULT_PASTE_API = 'https://plannotator-paste.plannotator.workers.dev';
const DEFAULT_SHARE_BASE = 'https://share.plannotator.ai';
There is no way to override these without:
1. Manually editing source files
2. Rebuilding the entire portal from source
3. Having deep knowledge of the codebase structure
Expected Behavior
For self-hosted setups, users should be able to:
- Configure custom paste service URLs via environment variables or config files
- See clear error messages if the paste service is unavailable
- Have step-by-step documentation on how to deploy and configure the paste service
- Understand the relationship between the paste service and the portal


Current Workaround
To make it work for self-hosted deployments, users must:
1. Modify packages/ui/utils/sharing.ts:
const DEFAULT_PASTE_API = 'http://plan.comact.com';
const DEFAULT_SHARE_BASE = 'http://plan.comact.com';
2. Rebuild the portal:
cd apps/portal
bun run build
cp -r dist/* /var/www/plannotator/
3. Ensure the paste service is running and properly configured with:
   - Environment variables set in /etc/environment (not just .env files)
   - CORS headers configured correctly
   - Systemd service file pointing to the compiled binary
4. Configure Nginx to proxy /api/paste requests to the paste service
Suggested Improvements
1. Add environment variable support to override default URLs:
   - VITE_PASTE_API_URL - Override paste service API URL
   - VITE_SHARE_BASE_URL - Override share URL base
2. Create self-hosting documentation covering:
   - How to set up the paste service (systemd, Docker, etc.)
   - Environment variable configuration
   - CORS setup for internal domains
   - Nginx proxy configuration examples
   - Troubleshooting guide
3. Improve error messages in the UI:
   - Instead of generic "(Short URL service unavailable)" show actual error details
   - Log specific failure reasons to browser console
   - Suggest how to debug/configure the service
4. Consider build-time configuration:
   - Support Vite environment variables for build-time URL configuration
   - Document how to customize these for self-hosted deployments
Environment Details
- Server: Linux (Ubuntu)
- Architecture: Self-hosted on internal network (10.1.34.66)
- Deployment: Nginx proxy + systemd services
- Paste service: Bun compiled binary
- Portal: Vite build served via Nginx
Impact
This issue affects anyone wanting to:
- Self-host Plannotator on internal networks
- Use custom domains for branding
- Disable cloud dependencies
- Run Plannotator in air-gapped environments
Without clear documentation and configuration options, these deployments require deep codebase knowledge and trial-and-error debugging.
Related Files
- packages/ui/utils/sharing.ts - Hardcoded defaults (lines 215-216)
- apps/paste-service/ - Paste service source
- apps/portal/ - Portal application
- docs/ - Missing self-hosting documentation
---
Note: The user was unable to find relevant documentation in the official docs and had to debug this through trial-and-error with the source code. A "Read The F-ing Manual" approach doesn't work when the manual doesn't exist for self-hosted setups.
---
**Labels to add** (if available):
- `documentation`
- `self-hosted`
- `feature-request`
- `needs-info`
**Assignee**: The repo maintainers will triage this appropriately.

[OliStarCooke]

The self hosting documentation isn't missing, but it's pretty light, especially for the installer portion.

IE.

git clone not mentioned before bun install.

We should also add what is client sided like the hooks installation and ENV variables setup VS server sided (static pages and/or paste service binary).

README should also figure some kind of development setup steps ideally (dependencies).

[backnotprop]

I will overhaul the self-hosted documentation through this weekend. I'm about to release a live sharing feature.