Self-Hosting Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides instructions for self-hosting the applications within the Nucleus repository. The project is an open-source library that powers a suite of personal productivity and well-being tools, including Nucleus, Memotron, and Pointron.
Currently, self-hosting is limited to the frontend client applications. This provides an offline-only version of the app, meaning data synchronization between devices is not possible. The development team plans to enable full-stack self-hosting in the future, which will include the backend services running on Cloudflare technologies.
Sources: README.md:25-27, client/landing/shared/faqs.data.ts:39-42, client/landing/routes/compare/memotronWheel.ts:245-250
Current Status & Limitations
- Frontend-Only: Only the client-side SvelteKit application can be deployed.
- Offline Mode: The self-hosted application will run in an offline-only capacity.
- No Data Sync: As there is no backend, you cannot sync data between different devices or browsers.
- Future Plans: Full application deployment, including the backend on Cloudflare (Workers, D1, R2), is planned for the future.
Sources: README.md:25-27, client/cx/contemporaries/notion.json:52-54
Repository Structure
The Nucleus project uses a monorepo architecture managed by Turborepo. The applications that can be self-hosted are located in the /apps directory. When deploying, you will need to select the specific application sub-folder you wish to host.
Sources: README.md:30-31, WARP.md:13-15
The diagram below illustrates the relevant part of the monorepo structure.
Sources: WARP.md:13-24, README.md:30-31
Deployment Process
The process for deploying a self-hosted, offline-only version of a Nucleus application involves cloning the repository, configuring environment variables, and deploying to a hosting provider of your choice.
This flowchart outlines the general steps for self-hosting.
Sources: README.md:29-37
Step 1: Get the Code
First, clone or fork the main repository to your local machine or GitHub account.
git clone https://github.com/21nOrg/nucleus.git
cd nucleus
Sources: README.md:29, CONTRIBUTING.md:6
Step 2: Configure Environment Variables
You must set two environment variables to correctly configure the application build. These variables determine which product is being built and where to fetch static assets from.
| Variable | Description | Possible Values | Example |
|---|---|---|---|
VITE_PRODUCT | Specifies which product to build. | memotron, pointron, nucleus | memotron |
VITE_STATIC_URL | The base URL for static assets like images and icons. | A valid URL pointing to a CDN. | https://cdn.21n.co |
Sources: README.md:32-36, CONTRIBUTING.md:9-12
You can set these variables in your deployment environment or in a local .env file for testing.
VITE_PRODUCT={{memotron | pointron | nucleus }}
VITE_STATIC_URL=https://cdn.21n.co
Sources: README.md:33-35
Step 3: Deploy
After configuration, you can deploy the chosen application from its sub-folder within the /apps directory to any static hosting provider (e.g., Vercel, Netlify, Cloudflare Pages). Follow the provider's instructions for deploying a SvelteKit application.
Sources: README.md:37, deployment/README.md:23-26
Future Self-Hosting Capabilities
The project roadmap includes the ability to self-host the entire application stack on a user's private cloud. This will enable data synchronization and full functionality without relying on the official managed service. This future setup is planned to utilize Cloudflare Workers for the backend, Cloudflare D1 for the database, and Cloudflare R2 for storage.
Sources: README.md:39-40, client/landing/routes/compare/memotronWheel.ts:245-250