Postmarks is a bookmarking site that you own yourself and can connect the Fediverse, interacting with other Postmarks sites as well as Mastodon/FireFish/any text-based ActivityPub platform. You can read more about it here:
The site allows the owner to add, edit and delete bookmarks, but only if a valid login is provided. Check the setup below to understand how to do that!
To set your app up:
- Create a
.envfile in the root of the project. - Add the line
PUBLIC_BASE_URL=<hostname>to your .env where <hostname> is the hostname of your instance. - Add the line
ADMIN_KEY=<key>to your .env where <key> is the password you'll enter when the browser prompts you, and another line forSESSION_SECRET=<secret>where <secret> is a random string used when hashing your session for use in a secure cookie. - Make a file called
account.jsonin the project root. Copy the contents ofaccount.json.exampleinto it and edit the values to set your@username, display name, bio, and avatar.- If you don't set a username, your default actor name will be 'bookmarks', so people will find you on the fediverse
@bookmarks@<hostname>. - You should update the avatar field in order to not hotlink to another server-- the value must be an absolute URL. If you change out the hostname and leave the existing filename, you will link to a statically hosted image on your server that was downloaded along with the rest of the Postmarks repo.
- If you don't set a username, your default actor name will be 'bookmarks', so people will find you on the fediverse
If you are using Docker compose you can run docker compose up or docker-compose up (depending on the version of Docker you are using) and Postmarks should be running. Otherwise, run npm run start on the command line. You can also use npm run start in any kind of app/container-management tool or SaaS provider that lets you define an entrypoint.
By default, Postmarks runs on port 3000. You can change this with a PORT=<number> entry in your .env. If you're running Postmarks behind a reverse proxy, configure it to send traffic from your Postmarks hostname to this port.
At this point, you should be able to load Postmarks in your browser using the hostname you configured. If you don't have a proxy to direct from the hostname, you'll need to add the port to the URL. In basic local development mode it should be available at http://localhost:3000 .
Once you're looking at the web interface in your browser, click on the Admin link in the footer, and enter the password (whatever you set ADMIN_KEY to in the .env). You should be logged in, at which point you can configure various settings, import bookmarks, and use the "Add" links in the header and footer (as well as the bookmarklet, available in the Admin section) to save new bookmarks.
Setting MASTODON_ACCOUNT in the .env file will cause a link to be added to the Postmarks home page that can be used for verification with your Mastodon account. See the Mastodon documentation for more details.
See CONTRIBUTING.md for more information on how to work with Postmarks' development environment as well as how to submit your changes for review.
- The "Postmarks" name is compliments of Casey C (no relation to Casey K), who brainstormed dozens of ideas for the name when Casey was first trying to rename the project. Thank you!
- Postmarks (in its default configuration) uses an edited version of Eynav Raphael's "Postmark Stamp" icon from The Noun Project.
- It also makes use of free fonts including Averia Sans and Public Sans.
- Much of the original form of the site's frontend is lifted from the starter projects available on Glitch. Thank you to all the people who have contributed to those projects over the years!
- Much of the original backend of the site is based off of Darius Kazemi's express-activitypub repo. I made a point not to just clone his repo from the start, but then ended up retyping most of it as I learned how things work. While some pieces have been upgraded, much of Darius' work creates the foundation for Postmarks' ActivityPub functionality.