Your profile. Your stack. Your rules.

The template lives in self-hosted-template. Visitors see your profile at /. Only a signed-in account whose UID has a matching owners/{uid} allowlist document with enabled: true can open /manage and publish changes.

Public route

/

Owner workspace

/manage

Sign-in route

/login

Profile document

profiles/main

• A root profile.config.ts with your identity, sections, links, socials, accent, and fallback profile.
• Email/password, Google, and GitHub owner sign-in through your configured authentication provider.
• Public reads and owner-only writes enforced infirestore.rules.
• A focused editor for identity, drag-sortable sections and links, optional icons or thumbnails, visibility, and social profiles.
• Optional public GitHub commit and coding activity with repository, placement, sampling, and display controls.
• A review-before-publish importer for JSON exported from the hosted Socialize dashboard.

• Node.js 22 and npm installed locally.
• A GitHub account, a fork of the repository, and a Vercel account.
• A dedicated cloud backend project used only by this self-hosted profile. Choose its database location carefully because that location cannot be changed later.
• A domain you control, if you want a custom production address.
• An optional fine-grained GITHUB_TOKEN with no access to private repositories if you need higher public API limits.

The backend web configuration uses public client identifiers; security comes from sign-in setup, authorized domains, and database rules, not from hiding those values. This starter does not need a server admin credential.

In /manage, enable developer activity, enter the public GitHub username, choose placement before or after links, and control commit history and coding activity independently. Commit controls cover the heading, 1–10 item limit, repository labels, and dates. Contribution controls cover the yearly total, calendar, month and weekday labels, legend, year selector, and languages.

Select repositories deliberately

Recent mode automatically samples up to three currently public repositories from recent push activity. Include mode uses only up to five selected owner/repository slugs. Exclude mode removes up to five selected slugs from the automatic set. Private or unavailable repositories are omitted.

The server route processes the public username, commit SHA and first-line message, repository and URL, commit date, push-day counts, and repository languages. Results come from GitHub, are not ownership verification, and may be sampled, delayed, incomplete, or unavailable. GitHub's public event feed can lag by about 30 seconds to six hours.

The stripped edition caches commit data for about 15 minutes and full contribution calendars for about one hour. Without a token, it shows a clearly labeled recent public sample in the same yearly grid. Add a Vercel Firewall rate-limit rule for /api/github-activity on a public deployment. If you add the optional server-only GITHUB_TOKEN, it enables the complete public contribution calendar, must not have private repository access, and must never use a NEXT_PUBLIC_ prefix.

1. 01

   Export from hosted Socialize

   Open Settings in the hosted dashboard and download the profile JSON export.

2. 02

   Import into the private manager

   Sign in at /manage, choose Import hosted JSON, and select the downloaded file. The import remains local draft state until you publish.

3. 03

   Review and publish

   Check identity, socials, section order, links, and developer activity, then publish. The importer reports hosted icon choices that need replacement and Firebase images that still depend on the old project.

4. 04

   Move uploaded images

   Re-upload any hosted avatar, link image, or section image to the dedicated self-hosted Firebase project before deleting the hosted account.

1. 01

   Fork and install the template

   Fork the repository into your GitHub account, clone your fork, and install dependencies from the template directory. Commit the generated package-lock.json so cloud builds use the same dependency graph.

   git clone https://github.com/YOUR_GITHUB_USER/socialize.git
   cd socialize/self-hosted-template
   npm install

2. 02

   Make the fallback profile yours

   Edit profile.config.ts. Replace the name, handle, sections, links, social URLs, accent color, and optional developer-activity defaults. KeepfirestoreDocumentPath atprofiles/main unless you also update the rules and understand the data-path change.

   firestoreDocumentPath: "profiles/main"
   profile: {
     name: "Your name",
     handle: "@your-handle"
   }

3. 03

   Connect the backend

   In your backend project dashboard, create a project, add a Web app, then create a profile database and a Storage bucket for optional link and heading uploads. Copy the six web-app values into a local environment file.

   Copy .env.example to .env.local and fill every NEXT_PUBLIC_FIREBASE_* value. Do not commit .env.local.

   cp .env.example .env.local
   # Add the backend web-app values to .env.local

4. 04

   Enable an owner sign-in method

   In your sign-in settings, enable at least one of Email/Password, Google, or GitHub. For GitHub, create an OAuth app and use the exact redirect URI shown in your provider dashboard, such ashttps://YOUR_PROJECT_ID.firebaseapp.com/__/auth/handler, as the GitHub authorization callback URL.

   Add localhost and your production hostname to your sign-in provider's authorized domains where required.

5. 05

   Create the owner account

   Create an email/password owner account in your dashboard, or attempt Google or GitHub sign-in once so the provider creates that user. Copy its UID from Authentication → Users. The first OAuth attempt can be rejected by the manager until the allowlist entry in the next step exists.

6. 06

   Add the owner UID to the database

   In the database, create owners/USER_UID and add the Boolean field enabled: true. Both the document ID and this exact field value are required for owner access. Browser clients cannot create or change owner records under the included rules.

   owners
   └── YOUR_OWNER_UID
       └── enabled: true

7. 07

   Deploy the database and storage rules

   The included rules allow anyone to read the public profile and allow writes only when the authenticated UID has a matching, enabled owner document. Storage rules make profile imagery publicly readable while restricting uploads to the signed-in enabled owner. Deploy both rule files before using the manager in production. On the first deploy, accept the Firebase Rules permission that lets Storage check the Firestore owner allowlist.

   npx firebase-tools@latest login
   npx firebase-tools@latest use --add
   npx firebase-tools@latest deploy --only firestore:rules,storage

8. 08

   Verify locally

   Start the development server, check the public profile, sign in at /login, edit one link at /manage, and confirm the change appears in a separate signed-out window.

   npm run dev
   # Open http://localhost:3000

Push your configured fork to GitHub, then import it in Vercel. Set the project's Root Directory to self-hosted-template so Vercel builds only the stripped edition. The checked-in vercel.json selects Next.js and runs the production environment validator before the build.

git add self-hosted-template
git commit -m "Configure my Socialize profile"
git push

In Vercel Project Settings → Environment Variables, add every value from .env.example for Production, Preview, and Development as appropriate, including the final NEXT_PUBLIC_SITE_URL. If developer activity needs higher GitHub limits, add the server-only GITHUB_TOKEN with no private-repository access. Configure a Vercel Firewall rate limit for /api/github-activity, then set VERCEL_FIREWALL_CONFIGURED=true for Production so the deployment validator can confirm that operational step. Redeploy after changing a public value because public Next.js variables are embedded into the browser bundle during the build.

Connect a custom domain

Add the domain in Vercel after the first successful deployment and apply the DNS records it supplies. Then add both the production domain and any Vercel preview domains you intend to use to your sign-in provider's authorized domains. GitHub sign-in still uses the provider's firebaseapp.com/__/auth/handler callback URL.

Back up the profile

Keep profile.config.ts current enough to serve as a useful fallback. For production data, schedule database exports or keep a separate machine-readable export in a private, access-controlled location.

Protect the owner boundary

Never create an owners/{uid} document for a visitor. Revoke old owners promptly, use multi-factor authentication where your provider supports it, and regularly review authorized sign-in domains and Vercel project access.

Take upstream updates deliberately

Keep your fork's changes in small commits. Review upstream diffs, run npm run typecheck and npm run build, then test sign-in, profile reads, owner writes, and a signed-out session before deployment.

Security problems in the template can be reported through the Socialize security page. Questions about configuration belong in the repository's issue tracker, without secrets or private account data.