ties

(previously named "linkblocks")

📚 A federated network to bookmark, share and discuss good web pages with your friends.

It's getting harder and harder to find good web pages. When you do find good ones, it's worth hanging onto them. ties is your own small corner of the web, where you can keep your favorite pages, and share them with your friends to help them find good web pages too.

🔭 ties is in an exploratory phase where we're trying out different ways to make it work well. You can try it out, but big and small things might change with every update.

Vision

• On ties, you can organize, connect, browse and search your favorite web pages.
• Share carefully curated or wildly chaotic collections of the stuff you really really like with other ties users and the whole world wide web.
• Follow users with a similar taste and get a feed of fresh good web pages every day. Browse others' collections to discover new web pages from topics you like.
• Annotate, highlight and discuss web pages together with your friends.
• Mark users as trusted whose standards for web pages match yours - and then search through all trusted bookmarks to find good pages on a specific topic. Add trusted users of your trusted users to your search range to cast a wider net.

See this blog post for more on the vision behind ties.

Related Reading

• Where have all the Websites gone? talks about the importance of website curation. ties is for publicly curating websites.
• The Small Website Discoverability Crisis similar to the previous link, it encourages everyone to share reading lists. By the author of the amazing marginalia search engine.

Installation and Configuration

⚠️ ties is in an alpha stage. Consider all data in the system to be publicly available, even bookmarks in private lists. Only single-user instances are supported.

You can run the container at ghcr.io/raffomania/ties. It's recommended to use the tag of the latest stable release, e.g. 0.1.0. If you're feeling adventurous, there's a latest tag which tracks the latest commit on the main branch.

With docker-compose

See doc/docker-compose.yml for an example configuration. Make sure to fill out the blank environment variables such as BASE_URL and the admin credentials, then start the server using docker-compose up. By default, the server will be exposed on port 3000.

Building from Source

Install the rust toolchain, version 1.88.0 or later. Then build the ties binary using:

cargo build --release

Running the Server Binary

ties is deployed using a single binary. If you've built the binary or downloaded it from GitHub releases, you can run the server using ties start. The only dependency is a PostgreSQL instance.

Configuring the Server

ties is configured through environment variables or command line options. Run ties start --help to for comprehensive documentation on the available options. Let's go over a few of the central knobs you might want to configure:

• DATABASE_URL: PostgreSQL Connection URI for connecting to the database.
• BASE_URL: Public URL the server is reachable at. Cannot be changed once the first user has been created.
• LISTEN: IP address and port to listen on.
• ADMIN_USERNAME, ADMIN_PASSWORD (Optional): Create an admin user with these credentials if it doesn't exist yet.
• OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ISSUER_URL, OIDC_ISSUER_NAME (Optional): Configuration for single-sign-on using an OIDC provider.
• TLS_CERT, TLS_KEY (Optional): Paths to TLS keypair, if you'd like to serve ties via TLS directly. If you don't set this, it's recommended to use a reverse proxy in front of ties.

Upgrading & Stability

By default, upgrades do not require manual intervention. The database is migrated automatically when the server starts.

If an upgrade does require manual intervention, it is marked with a new minor version (as long as we are pre-1.0), and will be called out prominently in the changelog.

Development Setup

Install the dependencies:

• Latest stable version of Rust (An older version might work as well, but is not tested)
• mkcert
  • Don't forget to run mkcert -install
• podman, for conveniently running postgres for development and tests

Install dependencies available via cargo:

cargo install cargo-run-bin

Copy .env.example to .env and edit it to your liking.

Optional: run cargo bin just install-git-hooks to automatically run checks before committing.

In the root of the repository, launch the server:

cargo bin just watch

Then, open [http://localhost:4040] in your browser.

Testing SSO with Rauthy

1. Run just start-rauthy to run rauthy in development mode in a container.
2. Open rauthy in your browser by going to localhost with the port specified by RAUTHY_PORT in your .env file.
3. Go to the admin area and log in as admin@rauthy.localhost with the password test.
4. Create a new client. Use {BASE_URL}/login_oidc_redirect as your redirect URI, with the base URL defined in your .env file. Set access and id algorithm to "EdDSA", if it's not already set.
5. Enter your client ID and secret in your .env file.
6. Restart the ties server. Click the "Sign in with Rauthy" button at the bottom of ties' login page. If it's not there, check the server logs to see if something related to OIDC went wrong.
7. Use the same admin credentials as above to log into rauthy again.

Writing Migrations

See the docs.

Technical Details

This web app is implemented using technologies hand-picked for a smooth development and deployment workflow. Here are some of the features of the stack:

• Type-safe and fast, implemented in Rust using the axum framework
• Snappy interactivity using htmx with almost zero client-side code
• Tailwind styles without NodeJS, integrated into the cargo build process using build scripts
• Compile-time verified HTML templates using htmf
• Compile-time verified database queries using SQLx
• Concurrent, isolated integration tests with per-test in-memory postgres databases
• Single-binary deployment; all assets baked in
• Integrated TLS; can run without a reverse proxy
• PostgreSQL as the only service dependency
• Built-in CLI for production maintenance
• Auto-reload in development without dropped connections

Software Bill of Materials

An up-to-date Software Bill of Materials can be found in the ties.cdx.json file.

Acknowledgements

ties is made possible with a donation from NGI Zero Commons Fund. NGI Zero Commons Fund is part of the European Commission's Next Generation Internet initiative, established under the aegis of the DG Communications Networks, Content and Technology. Additional funding is made available by the Swiss State Secretariat for Education, Research and Innovation (SERI).