A lightweight, single-account ActivityPub social platform powered by PHP, Python, SQLite, and Docker.
Live Demo · Documentation · Install · Report an Issue
- Overview
- Features
- Demo and Screenshots
- Prerequisites
- Installation
- Configuration
- Usage
- Upgrading an Existing Installation
- Architecture and Project Structure
- Testing and Validation
- Security
- Contributing
- Roadmap and Current Limitations
- Documentation
- License
- Author and Maintainers
- Contact and Support
XFedi is an open-source, self-hosted social networking application for people who want to maintain their own presence on the decentralized Fediverse. A single XFedi installation hosts one local account and can communicate with compatible ActivityPub servers, including Mastodon instances, without depending on a central social network.
Version 2.1.0 provides a modular PHP application, a Python background worker, SQLite persistence, and a Docker Compose deployment with Caddy. It combines a responsive social interface with account discovery, signed federation, public timelines, notifications, RSS feeds, website association checks, and administrative backup/restore tools.
XFedi is designed for personal instances, developers, small self-hosting environments, and Fediverse enthusiasts. It prioritizes ownership, a small deployment footprint, understandable code, and careful handling of remote content.
Scope: XFedi is a single-user, public-post ActivityPub server, not a full Mastodon replacement. It implements server-to-server ActivityPub but does not provide Mastodon's REST/client API or universal compatibility with every Fediverse implementation. See Current Limitations and FEDERATION.md.
- Responsive interface: Desktop, tablet, and mobile layouts, light/dark styling, accessible forms, and mobile sign-in.
- Posts and conversations: Publish public text and image posts, reply, mention accounts, browse hashtags, edit posts, and delete your own content.
- Engagement: Favourite/unfavourite, boost/unboost, and create linked quote posts with readable fallback links.
- Bookmarks: Save posts privately without broadcasting bookmark activity to remote servers.
- Three timeline views: Home (followed accounts), Local (locally authored content), and Federated (known public remote posts and selected public instance sources).
- Remote content presentation: Profile headers, image galleries, GIF/WebP/AVIF imagery, video/audio playback controls, and compatible incoming quote/boost previews.
- Link previews: Cards derived from supported Open Graph, Twitter, JSON-LD, oEmbed thumbnail, and WordPress metadata; untrusted embedded scripts are not executed.
- Notifications: Follow, reply, mention, favourite, boost, quote, and follow-response events; unread counts and read/unread management.
- Timezones: Per-account IANA timezone preference for display; network timestamps remain in UTC.
- ActivityPub server-to-server communication with actor, inbox/outbox, follow collection, and public Note support.
- WebFinger and NodeInfo endpoints for remote account and server discovery.
- Signed requests: RSA-SHA256 HTTP signatures and signed GET requests for compatible secure-mode peers.
- Activity handling: Follow/Accept/Reject, Create/Update/Delete, Like/Undo, and Announce/Undo where supported.
- Delivery reliability: Durable inbound/outbound queues, retries with backoff, deduplication, and replay protection.
- Remote search and instance sources: Resolve remote account/post identifiers and optionally import bounded public timeline samples from compatible instances.
- Human-readable URLs: Profiles such as
/@aliceand posts such as/@alice/123, while preserving canonical federation identifiers.
- RSS:
/feed.rss,/@username.rss, and/tags/hashtag.rssfor eligible local public content. - Search-engine discovery: Paginated XML sitemaps, robots endpoint, and social sharing metadata.
- Website association: Automated HTTPS checks that distinguish site reachability, profile backlinks/same-domain association, and stricter
rel="me"verification. - Backups and recovery: Database-plus-media backups, validation before restore, and identity-preserving migrations.
- Container isolation: PHP-FPM and Python worker containers, Caddy route allowlisting, private persistent data volume, and loopback-only host binding by default.
- Developer tooling: Automated tests, release validation documentation, operational health checks, and GitHub Actions CI.
Live demonstration: https://xfedi.xsukax.net/
Browse the public interface to explore the timeline, profiles, and navigation. Posting and account administration require authentication; the public demo is not an invitation to create accounts on the owner's instance.
| Desktop | Mobile |
|---|---|
![]() |
![]() |
Direct screenshot links: Desktop preview · Mobile preview · Remote profile preview
Screenshots are stored under
docs/and will render on GitHub once those image files are committed to the repository.
| Component | Requirement |
|---|---|
| Operating system | A host that supports Docker Engine or Docker Desktop (Linux recommended for servers) |
| Containers | Docker with the Compose v2 plugin (docker compose) |
| Domain | A stable, publicly resolvable hostname under your control |
| HTTPS | Public HTTPS, typically provided by an existing Cloudflare Tunnel |
| Connectivity | Outbound HTTPS/DNS from the containers; remote servers must reach public federation endpoints |
| Resources | Enough storage for the SQLite database, uploaded media, logs, and backups |
| Utilities | Git (optional for downloads); a POSIX shell and curl for helper scripts |
The supplied Docker image includes PHP 8.3, Python, PHP-FPM, and the necessary PHP extensions; no separate host PHP, Composer, Node.js, or npm installation is required for the container deployment.
- PHP 8.3+ with
pdo_sqlite,curl,openssl,mbstring,fileinfo, anddom. - Python 3.10+ and standard-library modules used by the project.
- A POSIX shell and local loopback networking for HTTP integration tests.
- Docker Compose v2 for the additional container and Caddy isolation checks.
git clone https://github.com/xsukax/XFedi.git
cd XFediIf you downloaded a release archive instead, extract it and change to the directory containing compose.yaml, index.php, and install.sh.
Choose a permanent hostname, for example social.example.com. Configure your existing Cloudflare Tunnel on the same machine as Docker to publish that hostname over HTTPS. The tunnel should forward HTTP to XFedi's loopback-only origin. The default service URL is:
http://localhost:80
Cloudflare must allow unauthenticated access to WebFinger, ActivityPub inbox/outbox and actor endpoints, NodeInfo, public media, RSS, and sitemap paths. Authentication challenges on these routes can break federation. Avoid caching authenticated pages.
chmod +x install.sh upgrade.sh backup.sh restore.sh verify.sh
./install.sh social.example.comReplace social.example.com with your real hostname, without https:// or a trailing path. If local port 80 is already in use, pass a different port:
./install.sh social.example.com 8080Configure your Cloudflare Tunnel origin to use the corresponding http://localhost:8080 URL. The installer:
- Validates Docker access and the hostname.
- Creates a private
.envwith the permanent federation identity. - Generates a random
XFEDI_SETUP_TOKENfor first-run account creation. - Builds and launches the
php,worker, andwebservices with Docker Compose. - Binds the HTTP origin to 127.0.0.1, rather than exposing it publicly.
Open https://social.example.com/ (or https://social.example.com/index.php) in your browser. Read the installation token from your private .env file, enter it in the initial setup form, and choose your account credentials. Passwords must be at least 12 characters long.
Do not publish .env or the setup token. The token helps prevent unauthorized first-account registration.
docker compose ps
./verify.sh
docker compose logs -f web php workerverify.sh checks the local origin and confirms that sensitive implementation paths are not directly served. A working local origin is necessary but not sufficient to prove federation works with external instances; complete the live federation checks before relying on interoperability.
If you do not want to use the installer:
cp .env.example .env
chmod 600 .envSet DOMAIN, LOCAL_PORT, FEDERATION_PATH=/index.php, and a securely generated XFEDI_SETUP_TOKEN (at least 24 random characters). Then run:
docker compose config --quiet
docker compose up -d --buildYou must configure public HTTPS/reverse proxy routing separately. See Configuration before enabling a deployment mode other than the default Cloudflare Tunnel.
Configuration is primarily read from the private .env file and passed into the containers by compose.yaml.
| Setting | Example / default | Purpose |
|---|---|---|
DOMAIN |
social.example.com |
Public HTTPS hostname; becomes part of the ActivityPub identity. Do not change after federation begins. |
LOCAL_PORT |
80 via install.sh |
Host loopback port where Caddy receives the tunnel's HTTP traffic. |
FEDERATION_PATH |
/index.php on fresh installs |
Canonical PHP path used in ActivityPub IDs; preserve the original value when upgrading. |
XFEDI_SETUP_TOKEN |
Randomly generated by installer | Private one-time setup authorization for the initial local account. |
TRUST_PROXY |
0 |
Enables trusted reverse-proxy handling; use only with a correctly isolated, trusted TLS proxy. |
ALLOW_INSECURE_HTTP |
0 |
Permits non-HTTPS browser cookies for local testing only; never expose this mode publicly. |
The Compose configuration constructs the PHP and worker XFEDI_URL as:
https://<DOMAIN><FEDERATION_PATH>
Identity is permanent. Changing the domain or canonical federation path can cause remote servers to treat your account and posts as an entirely different actor. The project deliberately retains the Compose project name xsukax-fediverse and persistent app_data volume to support legacy upgrades.
- Cloudflare Tunnel (default): Cloudflare provides public HTTPS; a host-installed tunnel connects to loopback HTTP at the selected local port. Leave
TRUST_PROXY=0andALLOW_INSECURE_HTTP=0unless you have a specific, reviewed reason to change them. - Another trusted TLS reverse proxy: Configure the proxy to send the correct
X-Forwarded-Proto: https, isolate the origin, and setTRUST_PROXY=1only when all requests reaching the origin come through the trusted path. - Local-only plain HTTP: Set
ALLOW_INSECURE_HTTP=1solely for a development machine or isolated LAN. This disables secure-cookie enforcement and must not be internet-facing.
Persistent SQLite data, uploads, signing keys, and background-job state live in the private Docker volume mounted at /var/lib/xsukax-fediverse inside the application containers. Caddy does not mount this volume. Keep the database, .env, archives, and signing keys out of the repository and away from publicly served paths.
| Area | Route |
|---|---|
| Home | / |
| Profile | /@alice |
| Individual post | /@alice/123 |
| Public Federated / Local | /public · /public/local |
| Sign in / Search | /auth/sign_in · /search |
| Public instance sources | /instances |
| Notifications / Bookmarks / Boosts | /notifications · /bookmarks · /boosts |
| Account settings | /settings |
| RSS | /feed.rss · /@alice.rss · /tags/example.rss |
| Sitemap / Robots | /sitemap.xml · /robots.txt |
| WebFinger | /.well-known/webfinger?resource=acct:alice@social.example.com |
| NodeInfo discovery | /.well-known/nodeinfo |
| Health endpoint | /healthz |
- Sign in to your XFedi instance.
- Use the Home composer to write a public post, include a link or mention, or attach supported imagery with a description.
- Open a post to reply or view its conversation; use the action controls to favourite, boost, bookmark, or publish a linked quote.
- Edit or delete your own posts from their available controls. You can also hide a remote post locally, then restore it through Settings; hiding does not delete the remote author's content.
Use Search to look up a remote handle (for example, @someone@mastodon.example) or a supported public post URL. Open the remote account and follow it. Remote actions are processed through signed ActivityPub requests and background queues, so remote delivery and counters may update after a delay.
The Federated timeline can also show a bounded sample of public posts from compatible instances configured under Instances. This feature does not silently follow every remote user and cannot bypass an instance that disables its public timeline API.
Open Settings to update your display name, bio, avatar, header, website, password, and display timezone. XFedi checks saved HTTPS website URLs and labels their status based on available evidence. A reachable site alone is not proof that you own it, and other Fediverse applications may have stricter verification rules.
# Container status
docker compose ps
# Live application logs
docker compose logs -f php worker web
# Origin availability and private-path protections
./verify.sh
# Inspect PHP configuration/requirements
docker compose exec -T php php index.php doctor
# Create a private SQLite-and-media archive
./backup.shFor recovery, use the supplied validated restore tool with an absolute backup path:
./restore.sh /absolute/path/to/xfedi-backup.tar.gz
# Only when you intend to overwrite an existing installation's data:
./restore.sh /absolute/path/to/xfedi-backup.tar.gz --replace
docker compose up -dA backup includes sensitive account material and private federation keys. Encrypt or securely store off-host copies, and retain .env separately. Never run docker compose down -v on an installation whose data you want to keep.
XFedi 2.1.0 includes an upgrade path from XFedi 2.0 and xsukax Fediverse v1.2. Do not install the new version under a second Compose project if it is intended to replace an existing federated identity.
- Back up the running installation, including the SQLite database, uploaded media, previous source files,
.env, and Docker volume. - Stop writes:
docker compose stop php worker. - Replace the application source with the new release in the same installation directory, preserving
.env, backups, and the Compose project name. - Keep the original
DOMAINandFEDERATION_PATH. For older installations withoutFEDERATION_PATH, preserve the legacy fallback; do not force/index.php. - Run
./upgrade.sh, which builds the new image, takes a pre-migration snapshot, performs additive migration, restarts services, and runs verification. - Confirm your actor URL, signing identity, post counts, images, and follows, then run the live interoperability checklist.
./upgrade.shImportant: Rollbacks require both the previous compatible application version and its pre-upgrade data snapshot. See CHANGELOG.md and the existing upgrade guidance in the source package before touching production data.
flowchart LR
Browser[Browser / Fediverse peer] --> HTTPS[Public HTTPS / tunnel]
HTTPS --> Caddy[Caddy · allowlisted routes]
Caddy --> PHP[PHP-FPM · XFedi application]
PHP <--> SQLite[(Private SQLite + uploads)]
PHP --> Jobs[(Durable federation queues)]
Worker[Python worker] --> Jobs
Worker --> PHPJobs[Private PHP job processor]
PHPJobs --> SQLite
PHPJobs --> Remote[Remote ActivityPub servers]
Caddy handles approved paths and forwards PHP requests; it does not expose private source modules or the data volume. The PHP modules serve the UI, authentication, persistence, ActivityPub endpoints, and application actions. Python supervises recurring background work and federation queue processing. See Architecture for the processing and trust-boundary details.
XFedi/
├── index.php # Public PHP front controller and CLI commands
├── app/
│ ├── core.php # Config, persistence, crypto, federation primitives
│ ├── features.php # Extended social, media, discovery functionality
│ ├── social.php # Social and remote-content helpers
│ ├── routes.php # HTTP routes and public protocol endpoints
│ ├── actions.php # Authenticated actions and session handling
│ ├── view_helpers.php # Presentation helpers
│ └── views.php # HTML rendering and views
├── assets/
│ ├── theme.css # Responsive application styles
│ └── ui.js # Progressive client-side enhancements
├── bin/
│ ├── backup.php # Consistent database/media export
│ └── restore.py # Validated archive import
├── docker/
│ ├── fpm.conf # PHP-FPM settings
│ └── php.ini # PHP runtime settings
├── tests/ # PHP, Python, integration, and operational tests
├── docs/
│ ├── ARCHITECTURE.md
│ ├── TESTING.md
│ ├── VALIDATION.md
│ └── preview-*.jpg # Desktop, mobile, remote-profile screenshots
├── .github/workflows/ci.yml # Automated CI jobs
├── .env.example # Example configuration (safe to commit)
├── compose.yaml # PHP, Python worker, Caddy, data volume
├── Dockerfile # PHP 8.3 / Python application image
├── Caddyfile # Restricted public HTTP routing
├── worker.py # Background scheduling and job supervision
├── install.sh # First-time deployment helper
├── upgrade.sh # Identity-preserving upgrade helper
├── verify.sh # Origin and sensitive-path checks
├── backup.sh # Backup wrapper
├── restore.sh # Restore wrapper
├── FEDERATION.md # Supported protocol behaviors and limits
├── SECURITY.md # Vulnerability disclosure guidance
├── CHANGELOG.md # Release history
├── LICENSE # Project licensing terms
└── README.md # This file
Generated files such as .env, SQLite databases, backups, signing keys, and Python caches are excluded from Git via .gitignore.
From a development checkout with the required local PHP and Python versions:
chmod +x tests/run.sh
./tests/run.shThis runs PHP, Python, and shell syntax checks; migration/core assertions; social and remote-content assertions; isolated HTTP integration tests; and backup/restore checks. It uses temporary state rather than the production volume.
docker compose config --quiet
docker compose build php
docker compose up -d --wait
./verify.sh
docker compose exec -T web caddy validate --config /etc/caddy/Caddyfile
docker compose exec -T php php index.php doctorDo these tests against an isolated installation/volume when validating a new release. In particular, confirm .env, source files, SQLite and WAL files, backup scripts, and .git contents cannot be downloaded through the public origin.
GitHub Actions is configured to test the application with PHP 8.3, 8.4, and 8.5 (using Python 3.12) and perform container build/origin-isolation checks.
The included release validation record reports 67 core/migration assertions, 43 social assertions, 11 HTTP scenarios, and 4 backup/restore tests performed in the original release authoring environment. Those results are not a substitute for testing your own environment. Live cross-server federation and production deployment acceptance have not been established by the package's local tests.
For release readiness, follow the responsive-browser matrix and live Mastodon acceptance procedure in docs/TESTING.md.
Security-related reports should be private. Do not publish credentials, signing keys, live database copies, backup archives, or working exploit details in a public issue.
- Check for a Private vulnerability reporting option under the repository's Security tab. If it is unavailable, contact the maintainer privately to arrange a safe disclosure channel.
- Include the affected version, impact, minimal reproduction steps using disposable data, and suggested mitigation if known.
- Follow the guidance in SECURITY.md for responsible disclosure.
Deployment recommendations: keep Docker, Caddy, PHP, and the host patched; enforce public HTTPS; isolate the local origin; protect .env and backups; avoid exposing the database; do not enable insecure HTTP publicly; review inbound federation and queue errors; and periodically test restore procedures.
XFedi implements signed federation requests, CSRF and session protections, content sanitization, outbound HTTP safety checks, and private persistent storage. These controls do not constitute a third-party security audit.
Contributions are welcome, especially reproducible bug reports, interoperability tests, documentation improvements, accessibility fixes, and focused security hardening.
- Search existing issues and pull requests for related work. Open an issue for a major or compatibility-changing proposal before implementing it.
- Fork the repository and create a descriptive branch such as
fix/remote-profileorfeat/accessibility. - Keep the PHP/Python architecture and one-account identity model in mind. Use PHP 8.3-compatible, readable, focused code; match nearby style and avoid unnecessary external dependencies.
- Add or update automated tests and documentation when behavior changes. Never commit
.env, secrets, private data, or production backup files. - Run
./tests/run.shand relevant container checks. For changes involving ActivityPub, record the remote software/version used for interoperability tests. - Open a pull request explaining the problem, approach, tests, backward-compatibility considerations, and any UI screenshots. Respond to review feedback and keep changes scoped.
Federation identity compatibility is especially important: migrations must preserve existing account, actor, object, and signing identifiers unless a carefully documented migration strategy explicitly addresses them. Security vulnerabilities should use the private reporting process above, not public pull requests containing exploit details.
XFedi focuses on a manageable personal instance. The following are not currently implemented and should not be assumed to work:
- Multiple local user accounts or public registration.
- Direct/private or followers-only posting and messaging.
- Mastodon REST API compatibility, OAuth, or third-party Mastodon client support.
- Poll creation, account migration (
Move), or federation relays. - Full quote approval/revocation under FEP-044f (linked quotes currently use a compatible fallback).
- Full-featured moderation dashboards, email/push notifications, or guaranteed synchronization with all Fediverse servers.
Potential contributions in these areas need explicit protocol, security, and migration design. For the precise implemented matrix, see FEDERATION.md.
| Document | Content |
|---|---|
| FEDERATION.md | ActivityPub operations, signatures, object types, and compatibility limits |
| docs/ARCHITECTURE.md | Components, data flow, persistence, and trust boundaries |
| docs/TESTING.md | Automated, container, browser, and cross-server test procedures |
| docs/VALIDATION.md | Validation performed for the 2.1.0 source package and remaining checks |
| CHANGELOG.md | Version history and major changes |
| SECURITY.md | Responsible vulnerability reporting |
XFedi is distributed under the GNU General Public License, version 3.0 (GPL-3.0). You may use, study, modify, and redistribute the software under the terms of that license, including the applicable source-code and notice obligations. See LICENSE for the full legal text. Contributions must be compatible with the project's license.
xsukax — Project owner and maintainer
XFedi contributors — See the repository's contributors and commit history.
- Questions, bug reports, and feature requests: GitHub Issues
- Code contributions: GitHub Pull Requests
- Releases and updates: GitHub Repository and CHANGELOG.md
- Security-sensitive reports: Follow Security and SECURITY.md
- Public demo: xfedi.xsukax.net
When requesting support, please provide the XFedi version, platform, deployment type, relevant redacted logs, steps to reproduce, and expected versus actual behavior. Never include passwords, installation tokens, signing keys, or private archives.
Own your social presence. Connect through the Fediverse.
Made and maintained by xsukax.


