Introduction

Welcome to the nbsp documentation.

This mdBook covers the nbsp software project, also known as non-breaking space. A thoughtful community forum platform.

What is nbsp?

nbsp is intended to become a platform that small communities can reach for when they want to create their own space. Away from the hostile internet and all the problems that the big social media platforms come with. Anyone should be able to have their own space for their community.

It is heavily inspired by Tildes and its plans to become a better place on the internet. Due to many reasons however, the development of the Tildes software project has stagnated. And its creator has recently announced that changes are extremely unlikely.

For this reason, I’ve decided to have an attempt of my own at creating a better place online.

Who is behind nbsp?

nbsp is created and being developed by bearbearean, an individual developer from Belgium.

You can contact me at bear@bearbearean.dev or create an issue on GitHub.

Anti-goals

Aside from the set of goals that nbsp aims to achieve, there are also a set of anti-goals nbsp aims to not achieve.

Mass appeal/adoption

nbsp will deliberately be designed against mass appeal and against mass adoption.

It is not the intention that nbsp will replace any social media platforms as they exist today or in the future. Instead nbsp will be designed to let admins carefully control their community’s growth, the interface will not be designed for maximum interaction, and users will be encouraged to spend less time engaging with the website.

People thrive when they are a part of other spaces as well, being the one-stop shop is not the way.

A mobile app

There will not be an “official” mobile app for nbsp.

Primarily because I have exactly zero experience with mobile development (though it would be fun to learn). Secondarily because I’d like to make the web interface as good to use on mobile as any app could be.

The reason for “official” being in scare quotes is that third-party apps will always be possible to be made by anyone with enough motivation. A structured API is not yet in the plans for nbsp but should there be a need for it by third-party app developers then that’s something that could be looked into.

Federation

nbsp will not implement federation.

It is my understanding that the federation protocols that exist today are both complex to implement correctly from a software perspective and also complex to administer from a server hosting perspective. Either of these things are enough of a downside to federation to not support it, but combined they make it clear I don’t want to head in its direction.

Besides the technological challenges, there is also the social impact that federation adds. Connecting many different instances together comes with a large burden on admins and moderators to keep the peace between all the instances.

Maintaining a healthy community requires, among other things, having a good grasp on who is let in to the community and kicking out those who cause issues. Implementing federation makes this significantly more difficult.

Administration

This chapter contains information useful for people wanting to host or already hosting their own nbsp instance.

Deployment

TODO: Write out proper details for deploying nbsp.

You can also find out how nbsp.party is deployed in the nbsp.party repository. It contains a set of Ansible playbooks designed to take a fresh Debian 13 server from zero to running nbsp.

Configuration

From the beginning of the nbsp development, instance-wide configuration has been considered through the use of a database table called nbsp_config.

Read more about configuring your nbsp instance in the Configuration section.

Database tips

Various tips and SQL snippets for commonly used nbsp operations are collected in the Database tips section.

Configuration

From the beginning of the development of nbsp, instance-wide configuration has been considered through the use of a database table called nbsp_config.

This table has a simple key-value structure where each key is unique and configures something about nbsp. For example, the nbsp_community_title key determines the title/the main name of the nbsp instance.

Making changes

To make changes to your nbsp configuration, the only option at the moment is to connect directly to the database with psql and run an UPDATE query. Because the nbsp_config table only has 3 columns: config_id, key and value, an update is easy to do:

UPDATE nbsp_config SET value = 'nbsp.example' WHERE key = 'nbsp_community_title';

Tip

Take care when working with lots of text to escape your single quotes by doubling them up:

UPDATE nbsp_config
SET value = 'I''m an apostrophe!' WHERE key = 'nbsp_community_subtitle';
/*            ^^ Escaped single quote */

Applying your changes

Once you’ve made a change to nbsp_config you may notice it is not updated immediately on a running instance. This is because at the moment the nbsp_config is only read on the startup phase of nbsp.

So to apply any changes you’ve made you will need to restart nbsp.

Available options

nbsp_base_url

The reachable base URL for the nbsp instance. This should start with https://

• Available in versions >=0.0.1
• Defaults to https://nbsp.example.com

nbsp_homepage_notice

An optional key to put some text or a notice that will be displayed in a yellow text box on the homepage.

• Available in versions >=0.0.1
• Defaults to NULL, no value

nbsp_community_title

The title or main name of the community. This is used in various places such as the <title>, the site header, etc.

• Available in versions >=0.0.2
• Defaults to non-breaking space

nbsp_community_subtitle

The subtitle or short description of the community. This is used in the site header below nbsp_community_title.

• Available in versions >=0.0.2
• Defaults to a thoughtful community forum platform

nbsp_html_head_extra

Any additional HTML you may want to put at the end of the <head> tag. Such as additional <link> tags or other things.

Note

The contents from this key are included as-is in the HTML, it is not sanitized before being inserted.

• Available in versions >=0.0.3
• Defaults to NULL, no value

nbsp_html_body_extra

Any additional HTML you may want to put at the end of the <body> tag. Such as additional <script> tags or other things.

Note

The contents from this key are included as-is in the HTML, it is not sanitized before being inserted.

• Available in versions >=0.0.3
• Defaults to NULL, no value

nbsp_cookies_key

Cookies will be encrypted using this secret key.

Warning

Don’t touch this key unless you’re 100% sure you need to.

If this is ever leaked or publicly shared, consider all encrypted cookies to be compromised. Stop nbsp, update the value to NULL in the database and restart nbsp. A new encryption key will be generated.

• Available in versions >=0.0.4
• Defaults to an encryption key generated by nbsp, if the value is empty.

nbsp_jwt_signing_key

JSON web tokens will be signed using this secret key.

Warning

Don’t touch this key unless you’re 100% sure you need to.

If this is ever leaked or publicly shared, consider all JSON web tokens to be compromised. Stop nbsp, update the value to NULL in the database and restart nbsp. A new JWT signing key will be generated.

• Available in versions >=0.0.4
• Defaults to a signing key generated by nbsp, if the value is empty.

nbsp_content_security_policy

The content security policy value to set on every HTTP response.

• Available in versions >=0.0.4
• Defaults to default-src 'self';

nbsp_enable_prometheus_metrics

Set this to true to enable the Prometheus metrics endpoint at http://127.0.0.1:3001/metrics. Note this uses the 3001 port as opposed to nbsp’s 3000 port.

• Available in versions >=0.0.4
• Defaults to false

Database tips

Various tips and SQL snippets for commonly used nbsp operations.

The SQL snippets can be run via psql.

Creating invite codes

Invite codes need a user_creator_id that indicates who created the invite code.

If you do not want to use a specific user for this, use the special nbsp system user that has -1 as its user_id:

INSERT INTO invites (user_creator_id)
VALUES (-1), (-1), (-1)
RETURNING invite_code;

Granting invites to users

To let users create invite codes themselves via the web interface, the user_invite_settings table record needs to be updated for that user.

If a user does not yet have a record in the user_invite_settings table, create one:

INSERT INTO user_invite_settings (user_id)
VALUES (3)
ON CONFLICT DO NOTHING;

Then to grant 10 invite codes to this user:

UPDATE user_invite_settings
SET available_invite_count = 10
WHERE user_id = 3;

Or using username by joining on the users table:

UPDATE user_invite_settings uis
SET available_invite_count = 10
FROM users u
WHERE uis.user_id = u.user_id AND u.username = 'bearbearean';

Development

Development environment

TODO: Write out details for the development environment.

Version release procedure

A GitHub Actions workflow using release-plz is set up to automatically create the CHANGELOG.md and a release PR whenever new commits are pushed to the main branch.

The release PR stays open until we want to release a new version, any changes to main will be added in the PR. When we want to release a new version, all we have to do is merge the PR and the actions workflows will take care of the rest.

Release-plz will publish the nbsp crate (using trusted publishing) and create a release on GitHub.

Once a new release is created on GitHub the release binary workflow will then compile the nbsp binary and upload it to the GitHub release.

Instances

If you’re hosting an nbsp instance and wish to add it to this list, please open an issue on GitHub with the relevant information.