Bit

Bit is a simple, web-based, self-hostable text sharing platform written in Java and Spring. You can access it from here(no frontend, yet).

General

Bit can be used both from the frontend(not yet available) and through the REST API. Before using it, read the following technical notices:

1. By default, each new "text"(from now on: post) added to the platform is anonymous and does not expire. In order to associate a new post to an identity, you first need to register a new user account. The registration process requires a unique username, a unique email address and a password. User accounts can NOT be modified or recovered; therefore if you lose your password, you will need to create a new account using a new email address.

2. Posts published with a valid user identity can be altered or deleted. In order to do that, you need to authenticate yourself with your credentials within the update/delete request. Anonymous posts, on the other hand, can NOT be altered or removed; if you think that a certain content goes against the terms of service, you can email the owner of the bit instance.

3. The expiration date controls whether the post can be showed or not, once the current date is greater or equal than the expiration date, the post is classified as expired and thus shall not be showed. Expired posts are NOT deleted but may be manually removed by the instance owner.

4. The bit platform is stateless, hence there is no such thing as user session. Every time you need to use your user account for a certain operation(e.g., create a new post with an identity or delete an existing, non-anonymous post) you will need to provide your user credentials.

5. Deleting an existing user, will result in a cascade delete of any existing post associated with that user.

Database

New posts are stored on a relational database(PostgreSQL) using the Spring ORM system(Hibernate). The architecture of the bit platform consists of two tables: bt_users and bt_posts. The former stores the user accounts, and it's defined as follows:

Column	Data Type	Nullable
user ID	String	false
email	String	false
password	BCrypt	false
username	String	false

The latter, instead, stores the posts, and it's defined as follows:

Column	Data Type	Nullable
post ID	String	false
content	String	false
creation date	YYYY-MM-DD date	false
expiration date	YYYY-MM-DD date	true
user ID	Foreign key constrain	true

The user password is stored using a BCrypt based hash. Each post can be associated with one user(eventually zero) while each user can be associate with multiple posts(eventually zero). The relationship is of the type "one to many" from the user's perspective.

Deploy

In order to deploy the bit platform, you will need to install Docker/Podman and docker-compose. Once done that, you can easily launch the backend using the following command:

$> docker-compose up -d

By default, the following parameters are used:

• SERVER_PORT: "3000";
• POSTGRES_USER: "bituser";
• POSTGRES_PASSWORD: "qwerty1234";
• POSTGRES_DB: "bit";
• SPRING_SECURITY_USER_NAME: "admin";
• SPRING_SECURITY_USER_PASSWORD: "admin".

Be sure to update these values by editing thedocker-compose.yml file. Once the containers are deployed, you can expose the application through a reverse proxy:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Endpoints

The backend exposes the following REST APIs:

POST New User(/users/new):

Description: Add new user.
Parameters: username(string), email(string) password(string).

DELETE Delete User(/users/delete):

Description: Delete an existing user.
Parameters: email(string) password(string).

GET Post List(/posts):

Description: Retrieve all users.
Parameters: none.

GET Post By ID(/posts/{postID}):

Description: Search a post by its ID.
Parameters: none.

GET Post By Title(/posts/bytitle):

Description: Search a post by its title.
Parameters: title(string).

POST New Post(/posts/new):

Description: Add a new post.
Parameters: title(string), content(string), expirationDate(YYYY-MM-DD), user(User).

PUT Edit Post(/posts/{postID}):

Description: Update an existing, non-anonymous post.
Parameters: title(string), content(string), user(User).

DELETE Delete Post(/posts/{postID}):

Description: Delete an existing, non-anonymous post.
Parameters: user(User).

Examples

Below there are some practical examples on how to use the REST API:

1. Add a non-anonymous, perpetual post(note: the user must exist)

POST request to /posts/new with the following body:

{
  "title": "Hello World",
  "content": "This is a example text snippet",
  "expirationDate": null,
  "user": {
    "email": "john@example.com",
    "password": "very_bad_pw"
  }
}

2. **Add an anonymous post with expiration date set to January 25, 2024 **

POST request to /posts/new with the following body:

{
  "title": "Hello World",
  "content": "This is a example text snippet",
  "expirationDate": "2024-01-25"
}

3. Delete post afj45c

DELETE request to /posts/afj45c with the following body:

{
  "email": "john@example.com",
  "password": "very_bad_pw"
}

Unit tests

The bit platform provides some unit tests for the post and the user controllers. You can find them in src/test. The unit tests are automatically executed during the container bootstrap process, to manually run them issue the following command:

$> ./mvnw test

License

This software is released under the GPLv3 license. You can find a copy of the license with this repository or by visiting the following page.