Org Social Host is a hosting service that allows you to host your social.org files online. It automatically provides you with a nickname and a system to update or share your file with other users.

graph LR
    User["👤 User"] -->|1. Signup| Host["🖥️ Org Social Host"]
    Host -->|2. Get vfile & public URL| User
    User -->|3. Upload social.org| Host
    Host -->|"https://example.com/nick/social.org"| Followers["👥 Followers"]

    style Host fill:#667eea,stroke:#764ba2,stroke-width:3px,color:#fff,font-weight:bold
    style User fill:#f093fb,stroke:#f5576c,stroke-width:2px,color:#fff
    style Followers fill:#43e97b,stroke:#38f9d7,stroke-width:2px,color:#fff

It is useful for:

• Taking your first steps in the Org Social community
• Hosting your public file online without your own server
• Synchronizing multiple devices or clients with the same social.org
• Learning how Org Social works before self-hosting

⚠️ If you don't update your social.org at least once a month, you will lose the domain and the nickname will be released.

This is a free service with automatic cleanup to ensure fair resource usage.

You need to have Docker and Docker Compose installed.

cp .env.example .env

nano .env

⚠️ Personal Use: If you only plan to use this service for yourself:

• Disable registration after creating your account: Set ENABLE_SIGNUP=false in your .env file and restart the service. Make sure to create your account first before disabling registration.
• Disable automatic cleanup: Set ENABLE_CLEANUP=false in your .env file to prevent your files from being automatically deleted due to inactivity. This ensures your social.org will remain hosted indefinitely.

• NGINX_PORT: The port where the service will be available (default: 8080)
  • Example: NGINX_PORT=8080 → Service available at http://localhost:8080
  • Example: NGINX_PORT=3000 → Service available at http://localhost:3000
  • Production: NGINX_PORT=80 → Service available at http://yourdomain.com
• SECRET_KEY: Django secret key (⚠️ MUST change in production!)
• DEBUG: Set to false in production
• ALLOWED_HOSTS: Comma-separated list of allowed hostnames
• SITE_DOMAIN: Your domain (e.g., host.org-social.org or localhost:8080)
  • Important: Must match the port if not using standard ports (80/443)
• MAX_FILE_SIZE: Maximum file size in bytes (default: 5MB = 5242880)
• FILE_TTL_DAYS: Days before inactive files are deleted (default: 30)
• ENABLE_CLEANUP: Enable automatic cleanup of inactive files (default: true)
  • Set to false to disable automatic deletion (recommended for personal use)
  • When disabled, files will never be automatically deleted
• STORAGE_PATH: Path to store social.org files (default: /app/storage)

docker compose up -d

To update your Org Social Host to the latest version:

# Navigate to your installation directory
cd /path/to/org-social-host

# Pull the latest changes
git pull

# Rebuild and restart services
docker compose up -d --build

# Apply database migrations (if any)
docker compose exec django python manage.py migrate

Go to http://localhost:8080/signup (or your configured domain) and choose a nickname.

curl -X POST http://localhost:8080/signup \
  -H "Content-Type: application/json" \
  -d '{"nick": "my-nick"}'

Replace my-nick with your desired nickname.

Response:

{
  "type": "Success",
  "errors": [],
  "data": {
    "vfile": "http://localhost:8080/vfile?token=abc123&ts=1700000000&sig=xyz789",
    "public-url": "http://localhost:8080/my-nick/social.org"
  }
}

If the nickname is available, you will receive 2 elements that you must keep very safe:

• vfile: A path that represents your social.org file in a unique and virtual way. You should not share it with anyone. The format is usually like this: http://localhost:8080/vfile?token=123456789&ts=1700000000&sig=abc123.
• public-url: The public URL where your social.org file will be hosted. You can share this URL with anyone you want. The format is usually like this: http://localhost:8080/my-nick/social.org.

If you use the org-social.el client, configure it as follows:

(setq org-social-file "YOUR_VFILE_HERE")  ;; Your vfile here
(setq org-social-my-public-url "YOUR_PUBLIC_URL_HERE")  ;; Your public-url here
(setq org-social-relay "https://relay.org-social.org/")  ;; Relay server

Next, edit your social.org file with M-x org-social-open-file and save it with C-x C-s to upload it to the server.

Once you have included some followers, you can open the timeline with M-x org-social-timeline.

The client will take care of updating your social.org file on the server every time you save it.

If you want to do it manually, you can use the following command:

curl -X POST http://localhost:8080/upload \
    -F "vfile=YOUR_VFILE_HERE" \
    -F "file=@/path/to/your/social.org"

Note: The vfile parameter should be the full vfile URL you received during signup.

If you wish to delete your social.org file from the server, you can do so with the following command:

curl -X POST http://localhost:8080/delete \
    -H "Content-Type: application/json" \
    -d '{"vfile": "YOUR_VFILE_HERE"}'

⚠️ This is a non-reversible action!

Alternatively, wait for 1 month (or configured TTL) without updating it, in which case it will be automatically deleted.

You may want to move your file from this host to another domain, hosting, or server; but you don't want to lose your followers (who are pointing to your host domain). In that case, you have a custom redirection feature for migration that is permanent (HTTP 301).

To do this, use the following command:

curl -X POST http://localhost:8080/redirect \
    -H "Content-Type: application/json" \
    -d '{"vfile": "YOUR_VFILE_HERE", "new-url": "https://my-new-domain.org/social.org"}'

What happens:

• You will no longer be able to update your file on this host
• Your public-url will redirect (HTTP 301) to the new URL you specified
• Your followers won't notice the change (automatic redirect)
• You can do this action as many times as you want

Although your followers won't notice the change, we recommend notifying them of the migration so they can update their social.org with the new URL.

To remove the redirection and return to the previous state where you could upload a file:

curl -X POST http://localhost:8080/remove-redirect \
    -H "Content-Type: application/json" \
    -d '{"vfile": "YOUR_VFILE_HERE"}'

This will:

• Remove the redirect
• Allow you to upload files again
• Resume normal hosting

/ - Basic information about the host service.

curl http://localhost:8080/

{
  "type": "Success",
  "errors": [],
  "data": {
    "name": "Org Social Host",
    "description": "Host your social.org files online",
    "version": "1.0.0"
  },
  "_links": {
    "self": {"href": "/", "method": "GET"},
    "signup": {"href": "/signup", "method": "POST"},
    "upload": {"href": "/upload", "method": "POST"},
    "delete": {"href": "/delete", "method": "POST"},
    "redirect": {"href": "/redirect", "method": "POST"},
    "remove-redirect": {"href": "/remove-redirect", "method": "POST"},
    "public-routes": {"href": "/public-routes", "method": "GET"}
  }
}

/public-routes - List all public social.org files hosted on the server.

This endpoint allows you to discover other users' public files and explore the Org Social community on this instance.

Request:

curl http://localhost:8080/public-routes

Response:

{
  "type": "Success",
  "errors": [],
  "data": [
    "http://localhost:8080/alice/social.org",
    "http://localhost:8080/bob/social.org",
    "http://localhost:8080/charlie/social.org"
  ]
}

Notes:

• Only active files (not redirected) are included in the list
• Files without content are excluded
• This endpoint is useful for discovering users and building community directories

/signup - Register a new nickname and get vfile token.

Request:

curl -X POST http://localhost:8080/signup \
  -H "Content-Type: application/json" \
  -d '{"nick": "alice"}'

Response:

{
  "type": "Success",
  "errors": [],
  "data": {
    "vfile": "http://localhost:8080/vfile?token=abc123&ts=1700000000&sig=xyz789",
    "public-url": "http://localhost:8080/alice/social.org"
  }
}

Errors:

• Nickname already taken
• Invalid nickname format (only alphanumeric, hyphens, underscores)
• Nickname too short (minimum 3 characters) or too long (maximum 50 characters)

/upload - Upload or update your social.org file.

Request:

curl -X POST http://localhost:8080/upload \
    -F "vfile=http://localhost:8080/vfile?token=abc123&ts=1700000000&sig=xyz789" \
    -F "file=@/path/to/your/social.org"

Response:

{
  "type": "Success",
  "errors": [],
  "data": {
    "message": "File uploaded successfully",
    "public-url": "http://localhost:8080/alice/social.org"
  }
}

Errors:

• Invalid vfile token
• File too large (exceeds MAX_FILE_SIZE)
• Invalid file format (must be .org file)
• Account is currently redirected (cannot upload)

/delete - Delete your hosted file.

Request:

curl -X POST http://localhost:8080/delete \
    -H "Content-Type: application/json" \
    -d '{"vfile": "YOUR_VFILE_HERE"}'

Response:

{
  "type": "Success",
  "errors": [],
  "data": {
    "message": "File deleted successfully"
  }
}

Errors:

• Invalid vfile token
• File not found

/redirect - Set up permanent redirect to new URL.

Request:

curl -X POST http://localhost:8080/redirect \
    -H "Content-Type: application/json" \
    -d '{"vfile": "YOUR_VFILE_HERE", "new-url": "https://my-domain.org/social.org"}'

Response:

{
  "type": "Success",
  "errors": [],
  "data": {
    "message": "Redirect configured successfully",
    "redirect-url": "https://my-domain.org/social.org"
  }
}

Errors:

• Invalid vfile token
• Invalid URL format
• File not found

/remove-redirect - Remove redirect and resume hosting.

Request:

curl -X POST http://localhost:8080/remove-redirect \
    -H "Content-Type: application/json" \
    -d '{"vfile": "YOUR_VFILE_HERE"}'

Response:

{
  "type": "Success",
  "errors": [],
  "data": {
    "message": "Redirect removed successfully"
  }
}

Errors:

• Invalid vfile token
• No redirect configured
• File not found

/<nickname>/social.org - Publicly accessible social.org file.

Request:

curl http://localhost:8080/alice/social.org

Response:

Returns the content of the social.org file with Content-Type: text/plain; charset=utf-8.

If the account has a redirect configured, returns HTTP 301 with Location header pointing to the new URL.

Errors:

• 404 if nickname not found
• 301 if redirected

All endpoints are accessible from any origin via CORS. This allows frontend applications to consume the API without restrictions.

Allowed Origins: * (all origins)

Allowed Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS

Allowed Headers: accept, accept-encoding, authorization, content-type, dnt, origin, user-agent, x-csrftoken, x-requested-with

This means you can build web applications, mobile apps, or any frontend that needs to interact with the Org Social Host API without CORS issues.

Example from JavaScript:

// Fetch public routes
fetch('https://host.org-social.org/public-routes')
  .then(response => response.json())
  .then(data => console.log(data));

// Create a new account
fetch('https://host.org-social.org/signup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ nick: 'my-nickname' })
})
  .then(response => response.json())
  .then(data => console.log(data));

The vfile token uses the following format:

http://domain/vfile?token={random_token}&ts={timestamp}&sig={signature}

• token: Cryptographically random token (256 bits)
• ts: Unix timestamp when the token was created
• sig: HMAC-SHA256 signature of token:timestamp:nickname using Django's SECRET_KEY

This ensures:

• Tokens cannot be guessed
• Tokens cannot be forged
• Tokens are tied to specific accounts
• Tokens can be validated without database lookups

Files are stored in the STORAGE_PATH directory with the following structure:

storage/
  alice/
    social.org
  bob/
    social.org

A scheduled task runs daily to clean up:

• Files that haven't been accessed in FILE_TTL_DAYS (default: 30 days)
• Files are permanently deleted (non-recoverable)
• Nicknames are released for reuse

Removes stale files that haven't been updated within the TTL period.

Task: cleanup_stale_files()

You can manually trigger cleanup:

docker compose exec django python manage.py shell -c "from app.hosting.tasks import cleanup_stale_files; cleanup_stale_files()"

docker compose exec django python manage.py test

Except for serious errors, this service is free and does not offer technical support.

Open an issue in this repository if:

• An endpoint is not working as it should
• The service is down
• There is a serious security error
• You have a suggestion for improvement
• You want to contribute to the project

Technical support requests for individual user problems will not be addressed, nor will accidentally deleted files or files lost due to inactivity be recovered. It will also not be possible to reserve nicknames or domains, recover lost vfiles, or transfer nicknames between users.

This project is licensed under the MIT License.

• Org Social - The main specification
• Org Social Relay - P2P system for mentions, replies, and groups
• org-social.el - Official Emacs client
• Awesome Org Social - Collection of clients and libraries