Simple Web-based text sharing platform https://bit.marcocetica.com
Go to file
Marco Cetica 7820d875f2
Added documentation and CI pipeline
2024-01-16 09:24:04 +01:00
.github/workflows Added documentation and CI pipeline 2024-01-16 09:24:04 +01:00
.mvn/wrapper First upload, added controllers layout 2024-01-09 09:43:11 +01:00
src Added documentation and CI pipeline 2024-01-16 09:24:04 +01:00
.gitignore First upload, added controllers layout 2024-01-09 09:43:11 +01:00
Dockerfile Added documentation and CI pipeline 2024-01-16 09:24:04 +01:00
LICENSE Added documentation and CI pipeline 2024-01-16 09:24:04 +01:00
README.md Added documentation and CI pipeline 2024-01-16 09:24:04 +01:00
docker-compose.yml Added documentation and CI pipeline 2024-01-16 09:24:04 +01:00
mvnw First upload, added controllers layout 2024-01-09 09:43:11 +01:00
mvnw.cmd First upload, added controllers layout 2024-01-09 09:43:11 +01:00
pom.xml Added documentation and CI pipeline 2024-01-16 09:24:04 +01:00

README.md

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"
  }
}
  1. **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"
}
  1. 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.