📚 Macagram Documentation

Complete guide to your self-hosted social platform. Everything you need to know.

✨ Features Guide

📝 Posts & Feed

• Rich text: **bold** *italic* `code` — Markdown support
• @mentions: Type @username to tag someone — clickable profile link
• #hashtags: #topic — clickable, searchable across all posts
• Links: URLs auto-linkify. Link previews auto-fetch title, image, description
• Images: Upload images with posts. Click to open lightbox
• Specs sharing: Check "📎 Specs" to attach your device specs
• Post editing: Click ✏️ on your own posts to edit
• Delete: Click 🗑️ to delete your posts
• Bookmarks: Click 🔖 to save posts for later

❤️ Reactions

• Click 🎉 on any post → emoji picker with 10 emojis
• Click any emoji badge to react with that emoji
• Top 3 reactions shown as badges. Total count displayed
• Your reaction highlighted in indigo

💬 Comments

• Click 💬 count on any post to expand comments
• Write a comment and press Send
• Delete your own comments with ×

💬 DMs (Direct Messages)

• Click 💬 on any user's post to DM them instantly
• Use ✉️ New Message in DMs tab to DM any user
• Unread message count badge on DMs tab

🎬 Videos

• Upload videos (any format). Stored on your 500GB drive
• Featured video row at top of feed (latest 8)
• Delete your own videos

📱 Shorts

• Upload short vertical videos. Max-height viewport display

🔴 Live Streaming

• Start Stream: Screen sharing (desktop) or camera (mobile)
• Watch: Join stream in real-time via WebRTC
• Peer-to-peer — no server processing. Low latency

🎮 Mini Games

• Click 🎮 Game in post form to create Tic-Tac-Toe
• Anyone can play by clicking cells directly in the post
• First player is X, second is O. Play Again button on win/draw

🎨 Themes

• Click 🌙/☀️/◼ in the header to switch Dark / Light / OLED
• Preference saved in localStorage

🔐 Security

• Password: Change in Account tab
• Passkeys: Register Touch ID / fingerprint. WebAuthn standard
• 2FA (TOTP): Scan QR with Authenticator app. 6-digit codes
• Security Question: Set for password recovery
• Email: Add email for notifications + recovery

📊 Analytics

• Account tab shows: total posts, likes received, followers, DMs
• Real-time stats from your database

🤖 Bots & API

• One-Click Bot: Instant webhook URL. POST {"content":"hi"} — done
• API Keys: Create keys for full API access
• Bearer Auth: Authorization: Bearer m_YOURKEY
• Bot SDK: Examples in curl, Python, Node.js

👤 Profile Customization

• Upload banner image + profile picture
• Set display name, bio, location, website, pronouns, status
• Pick accent color (8 choices)
• Export all your data as JSON

📱 QR Code Login

• Scan QR on your phone → log in there → desktop auto-logs in

🔍 Global Search

• Search bar at top of Feed — searches posts, users, comments

🔑 OAuth Login Setup

GitHub

1. Go to GitHub Developer Settings → OAuth Apps → New
2. Callback URL: https://YOUR-DOMAIN/api/auth/github/callback
3. Set env: GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET

Discord

1. Go to Discord Developer Portal → OAuth2
2. Add Redirect: https://YOUR-DOMAIN/api/auth/discord/callback
3. Scopes: identify email

Google

1. Go to Google Cloud Console
2. Create OAuth Client ID → Web Application
3. Redirect URI: https://YOUR-DOMAIN/api/auth/google/callback

GitLab

1. Go to GitLab Applications
2. Redirect URI: https://YOUR-DOMAIN/api/auth/gitlab/callback
3. Scopes: read_user

🖥 Self-Hosting Guide

Requirements

• Node.js 18+
• External drive recommended (stores DB + uploads)
• Cloudflare tunnel or ngrok for public access

Quick Start

cd ~/Desktop/login-app
npm install
NODE_ENV=production node server.js

Cloudflare Tunnel

cloudflared tunnel --url http://localhost:3000

Database

Stored on your external drive at /Volumes/drive. 1/users.db. SQLite, no setup needed.

Uploads

Images/videos stored at /Volumes/drive. 1/uploads/. No size limits (your drive, your rules).

Environment Variables

• NODE_ENV=production — Production mode
• GITHUB_CLIENT_ID / SECRET — GitHub OAuth
• DISCORD_CLIENT_ID / SECRET — Discord OAuth
• GOOGLE_CLIENT_ID / SECRET — Google OAuth
• GITLAB_CLIENT_ID / SECRET — GitLab OAuth
• EMAIL_FROM — Sender email address
• APP_URL — Public URL for email links