{"id":13570685,"url":"https://github.com/benbrown/shuttlecraft","last_synced_at":"2025-04-07T12:10:41.669Z","repository":{"id":65220713,"uuid":"570962490","full_name":"benbrown/shuttlecraft","owner":"benbrown","description":"a single user activitypub server - join the federation!","archived":false,"fork":false,"pushed_at":"2023-12-15T02:47:02.000Z","size":1530,"stargazers_count":260,"open_issues_count":50,"forks_count":30,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-04-13T21:01:32.172Z","etag":null,"topics":["activitypub","benbrown","blogging","fediverse","indieweb","microblogging","rss","socialmedia"],"latest_commit_sha":null,"homepage":"https://shuttlecraft.net","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benbrown.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-11-26T17:45:03.000Z","updated_at":"2024-04-03T09:23:04.000Z","dependencies_parsed_at":"2023-02-13T23:30:44.613Z","dependency_job_id":"f1fc442b-38ce-4d4e-bc30-79bf2ff4f053","html_url":"https://github.com/benbrown/shuttlecraft","commit_stats":{"total_commits":241,"total_committers":5,"mean_commits":48.2,"dds":"0.13278008298755184","last_synced_commit":"ef489a33c92ed1857509ed57d09fa55fd7811da3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benbrown%2Fshuttlecraft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benbrown%2Fshuttlecraft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benbrown%2Fshuttlecraft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benbrown%2Fshuttlecraft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benbrown","download_url":"https://codeload.github.com/benbrown/shuttlecraft/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423496,"owners_count":20936622,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["activitypub","benbrown","blogging","fediverse","indieweb","microblogging","rss","socialmedia"],"created_at":"2024-08-01T14:00:54.217Z","updated_at":"2025-04-07T12:10:41.652Z","avatar_url":"https://github.com/benbrown.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Services","Applications"],"sub_categories":[],"readme":"# SHUTTLECRAFT by Ben Brown\n\nThis is a project to create an \"easy\" way to participate in the ActivityPub \"Fediverse\" and other indie web protocols like RSS.\nThis was created and is maintained by [Ben Brown](https://benbrown.com).\n\nCurrently, this means:\n\n- a stand-alone NodeJS web application \n- with no external service dependencies\n- that is hostable on Glitch or commodity virtualhost\n\nIncluding features:\n- Follow people (on Mastodon, other instances)\n- Compose posts and deliver on the web, and also via ActivityPub, RSS\n- Fave, boost and reply to posts\n- View notifications\n- Send and receive DMs\n- Block people or instances\n\nNot yet supported:\n- Media uploads\n\n## Warning: Experimental Software! \n\nThis software should be considered an EXPERIMENTAL PROTOTYPE.\nDo not use it to store or exchange sensitive information.\n\n- This software creates publicly available web endpoints.\n- This software sends outbound web requests.\n- This software reads and writes to the filesystem!\n- This software has not been audited for potential security problems!!\n\nBecause of the way the Mastodon works, once you start to engage with\nusers on other instances, you will start to receive traffic from a\nwide array of other instances -- not all of which is necessary or \nrelevant to you. As a result, operating this software on a small basis\nmay result in unexpected amounts of incoming traffic.\n\n## Warning: Known limitations!\n\nMy goal with this app is to not use any major external services.\nAs a result, all data is written as PLAIN TEXT FILES to the disk.\n\nRight now, the app builds an IN-MEMORY INDEX of EVERY SINGLE POST.\nThis will work for several thousand posts, but ... maybe not for 10,000s of posts.\nI'm not sure how far it will go. I have ideas about being able to\nshard the index into multiple files and page through it, etc. But.\n\nALSO, there is nothing fancy happening in terms of queuing or rate\nlimiting outgoing posts. When you post, it will send out HTTP requests\nright away, all at once. This may cause issues.\n\n## Acknowledgements\n\nThis project owes a great debt to @dariusk's excellent [express-activitypub](https://github.com/dariusk/express-activitypub) repo.\nMy work started from his reference implementation, and there are many lines of code cribbed from his work.\n\n## Bug Reports \u0026 Contributions\n\nPlease file bugs on Github:\nhttps://github.com/benbrown/shuttlecraft/issues\n\nPlease read the [contributor's guide](CONTRIBUTING.md) before sending pull requests.\n\n## Install\n\nQuick start: [Remix on Glitch](#easiest-glitch)\n\nClone the repo:\n`git clone git@github.com:benbrown/shuttlecraft.git`\n\nEnter folder:\n`cd shuttlecraft`\n\nInstall node dependencies:\n`npm install`\n\nYou are ready to run! But first, set your configuration.\n\nWhen you are ready to start, run:\n`npm start`\n\n## Config\n\nInitial configuration of your instance is done by editing the\n.env file to include your desired USERNAME, PASSWORD, and DOMAIN NAME.\nThese values MUST BE SET before you launch the application, as\nthey are used to generate your account details, including your\nFediverse actor ID.\n\nIn the .env file, put:\n\n```\nUSERNAME=yourusername\nPASS=yourpasswordforadmintools\nDOMAIN=yourdomainname\nPORT=3000\n```\n\nUSERNAME and PASS are required to login to the private dashboard tools.\n\nWhen you launch the app for the first time, these values will be used\nto create the `.data/account.json` file which is the source of your\npublic account information, and will be used for many operations.\n\nThere is currently no UI built to view or manage your account. If you\nneed to make updates, edit the JSON directly.\n\nHOWEVER PLEASE NOTE that your ID is a real URL, and it must reflect\nthe real URL served by this app. Also note that it is embedded in\nevery post you write - so if you change values in the `account.json` file,\nyour previous posts may break.\n\n\n## Login\n\nTo login, visit `https://yourdomain.com/private` and provide the username and password from your .env file\n\n\n\n## Debugging\n\nIf you want more logging or want to see what is happening in the background,\nenable debugging by adding DEBUG=ono:* to the .env file, or starting the app\nwith:\n\n`DEBUG=ono:* npm start`\n\n## Where is my data?\n\nAll of the data is stored in the `.data` folder in JSON files.\n\nIncoming activities will be in `.data/activitystream`. Each incoming\npost is in a dated folder, for example `2022/12-01/GUID.json`\n\nLocal posts are in `.data/posts`\n\nCached user information is in `.data/users`\n\nFollower list, following list, like list, boost list, block list,\nand notifications can all be found in their own files at the root\nof the `.data` folder. This is your data! Back it up if you care \nabout it.\n\n\n## Host\n\nThis is a node app that runs by default on port 3000, or the port\nspecified in the .env file.\n\nIn order to play nice with the fediverse, it must be hosted on an\nSSL-enabled endpoint.\n\n### Easiest: Glitch\n\nUse Glitch to create a new project! Glitch will provide you with hosting for your instance of Shuttlecraft,\nand you can start for FREE!\n\nIt all starts when you click this link -\u003e [Remix this project on Glitch](https://glitch.com/edit/#!/import/github/benbrown/shuttlecraft) \u003c--\n\nWHOA! What happened? Well, a copy of the Shuttlecraft code was sent to a new, unique, owned-by-you web server and it started getting set up. You just need to make it yours by following these steps:\n\n1. First, make sure the URL of your Glitch project is the one you like. You can change it in the \"Settings\" menu.\n2. Then, configure the options [as described above](#config) using the .env editor.\n3. Finally, login to the dashboard at `https://yourdomain.glitch.me/private`.\n4. Done!\n\n### Basic: Reverse proxy\n\n1. Clone the repo to your own server.\n2. Configure it and set it up to run on a port of your choosing.\n3. Configure Caddy or Nginx with a Certbot SSL certificate.\n4. Configure your domain to proxy requests to the localhost port.\n\nA sample `Caddyfile` is included in the repo. [Install Caddy](https://caddyserver.com/download) and run:\n```\ncaddy run --config Caddyfile\n```\n\n### Advanced: Docker\n\n1. Clone the repo.\n2. Build the image:\n   ```\n   docker build . --tag \"${yourRegistryUsername}/shuttlecraft:latest\"\n   ```\n3. Test locally:\n   ```\n   docker run -e PORT=3000 -e DOMAIN=\"your-domain.com\" -e USERNAME=\"yourUsername\" -e PASS=\"yourPassword\" -p \"3000:3000\" \"${yourRegistryUsername}/shuttlecraft\"\n   ```\n4. Push the image to your registry:\n   ```\n   docker push \"${yourRegistryUsername}/shuttlecraft:latest\"\n   ```\n5. Deploy the image to your container platform with the required environment variables (`DOMAIN`, `USERNAME`, `PASS`). \n6. Configure a web service to proxy requests to the container port and provide HTTPS (see \"Reverse proxy\" above). \n\n## Customize\n\nThis app uses HandlebarsJS for templating.\n\nCustomize the public pages:\n- Templates are in `design/public/home.handlebars` and `design/public/note.handlebars` and `design/layouts/public.handlebars`\n- CSS is in `public/css/main.css`\n\nCustomize your avatar:\n- Replace `public/images/avatar.png`\n- As necessary, update the url in `.data/account.json` inside the actor.icon.url field\n\nCustomize the backend:\n- Templates are in `design/dashboard.handlebars` and `design/notifications.handlebars` and `design/layouts/private.handlebars`\n- Some common components in `design/partials`\n- CSS in `public/css/secret.css`\n\nTo block users or instances:\n- Add an entry to the file at `.data/blocks`\n- You can block a user using their actor ID (something like https://foo.bar/@jerk) or their entire domain (https://foo.bar/)\n- Restart the app \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenbrown%2Fshuttlecraft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenbrown%2Fshuttlecraft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenbrown%2Fshuttlecraft/lists"}