https://github.com/d-indifference/kashiwa
Yet another imageboard implementation
https://github.com/d-indifference/kashiwa
chan-style-imageboard docker docker-compose ffmpeg futaba futabachannel gplv2 imageboard imageboard-engine imagemagick nest nestjs nodejs postgresql prisma prisma-orm pug typescript wakaba website
Last synced: 5 months ago
JSON representation
Yet another imageboard implementation
- Host: GitHub
- URL: https://github.com/d-indifference/kashiwa
- Owner: d-indifference
- License: gpl-2.0
- Created: 2025-04-03T13:18:32.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-10-16T13:16:17.000Z (8 months ago)
- Last Synced: 2025-10-17T11:36:05.195Z (8 months ago)
- Topics: chan-style-imageboard, docker, docker-compose, ffmpeg, futaba, futabachannel, gplv2, imageboard, imageboard-engine, imagemagick, nest, nestjs, nodejs, postgresql, prisma, prisma-orm, pug, typescript, wakaba, website
- Language: TypeScript
- Homepage:
- Size: 1.36 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Kashiwa Imageboard engine
Kashiwa is a work-in-progress imageboard implementation using Nest.js
In this application, there is currently limited functionality,
but we have just begun development, and you have every opportunity to
follow it through to the final release :).
## Key Features
- Easy to install: simply clone the project, add an `.env` file ([see description below](#run-the-application-with-docker)), and start working with the application
- Configuration options: basic setup is done via a configuration file, but during operation you can customize page content and board functionality
- Extensive capabilities for creating and customizing boards
- Traditional imageboard features such as sage, tripcodes, text formatting (still a work in progress), captcha, anti-flood, thread hiding, and style switching
- Oekaki board support is available (for browsers that support ECMAScript6+)
- The ability to configure the receipt of the poster's country flag by its IP
- The ability to pin threads and disable posting in them individually
- Support for uploading the most popular image, video, and audio formats, as well as the ability to upload torrents (yo-ho-ho! 🏴☠️) and .swf files
- Ability to add an administrative team: registered users can be either administrators or regular moderators
- Configure a spam filter using JavaScript regular expressions
- Ability to temporarily ban users who break the board’s rules, as well as set up an IP and User-Agents blacklists to block access entirely
- The engine supports database dumps and cached board backups — your data will be safe
- Initial REST API support for retrieving post information (detailed Swagger documentation available)
- Adding banners. Simply upload your banner images to `./kashiwa/static/img/banners`
- All localizable strings are stored in one place, making it easy to add new site translations
## Installation and Launch
### Run the application with Docker
After saving the source code, do the following:
1. Make `.env` file in your `kashiwa` project root:
```sh
$ cd kashiwa
$ touch .env
```
2. Fill the `.env` file with the following values:
```dotenv
POSTGRES_HOST='db.kashiwa'
POSTGRES_PORT=5432
POSTGRES_USER='postgres'
POSTGRES_PASSWORD='postgres'
POSTGRES_DB='kashiwa'
PGDATA='/var/lib/postgresql/data/pgdata'
DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}?schema=kashiwa"
KASHIWA_PHYSICS_VOLUME_POSTGRES='/var/lib/postgresql/data' # or you can change it to any other physical location you wish
KASHIWA_PHYSICS_VOLUME_APPLICATION='/var/lib/application/data' # or you can change it to any other physical location you wish
KASHIWA_CONFIGURATION_FILE='configuration.yml'
NODE_ENV='production'
```
3. Edit configurations in the file `configuration.yml` as you wish,
but we strongly recommend you to change default values by paths `secure.user.salt-rounds` and `secure.session.secret`.
When the application starts for the first time and no persistent application volume (`KASHIWA_PHYSICS_VOLUME_APPLICATION`) exists yet,
Kashiwa automatically creates it and writes several default configuration files inside — including the list of allowed CORS origins.
This list defines which domains (origins) are allowed to access your API from a browser.
If you don’t configure it beforehand, the application will use the preset from your `configuration.yml`
Example default section in configuration.yml:
```yaml
http:
port: 3000
cors:
allowed-origins:
default-preset:
- 'http://127.0.0.1'
- 'http://localhost'
```
You must add to this list the addresses from which your application will be accessible, for example, if your domain is https://example.com/, add the following lines to your `configuration.yml`:
```yaml
http:
port: 3000
cors:
allowed-origins:
default-preset:
- 'http://127.0.0.1'
- 'http://localhost'
- 'https://example.com'
```
On the first startup, Kashiwa will create the file `allowed-origins` (inside the application volume)
and populate it using this preset.
You can later edit that file directly to update allowed origins without rebuilding the container.
4. Next run the following commands:
```sh
$ docker compose build
$ docker compose up
```
Then go to [localhost](http://localhost).
And now you're awesome! Enjoy using the application!
Now you can go to [localhost/kashiwa/auth/sign-up](http://localhost/kashiwa/auth/sign-up) and create your first admin profile.
### Run the application without Docker
If you want to run **Kashiwa Imageboard Engine** without Docker, you need to make sure the following dependencies are installed on your system:
* **Node.js** (version 23.11.0 or higher)
* **Nginx** (optional, but recommended to configure as a reverse proxy. [Example configuration for HTTP](https://github.com/d-indifference/kashiwa/blob/main/nginx/nginx.conf))
* **PostgreSQL** (version 13.3 or higher)
Additionally, we recommend checking if the `pg_dump` utility is available on your system:
```sh
$ pg_dump --version
```
If it is missing, install it with the following command:
```sh
$ sudo apt-get update && sudo apt-get install postgresql-client
```
We also recommend making sure that `@nestjs/cli` is installed globally. If not, install it as follows:
```sh
$ npm i -g @nestjs/cli
```
So, after completing the steps above, let’s proceed with installing the imageboard engine:
1. Clone the repository and install the dependencies:
```sh
$ cd kashiwa
$ npm ci
```
Optionally, to make sure the application works, you can run the tests:
```sh
$ npm run test
```
2. Install the following utilities on your system (if not already installed):
* `imagemagick`
* `ffmpeg`
* `zip`
```sh
$ sudo apt-get update && sudo apt-get install -y imagemagick ffmpeg zip
```
3. In PostgreSQL, create a database and a schema:
```postgresql
CREATE DATABASE kashiwa WITH OWNER postgres;
```
```postgresql
CREATE SCHEMA IF NOT EXISTS kashiwa;
```
4. Create a `.env` file with the parameters below:
```dotenv
# your postgres instance host
POSTGRES_HOST='localhost'
# your postgres instance port
POSTGRES_PORT=5432
# your postgres username
POSTGRES_USER='postgres'
# your postgres password
POSTGRES_PASSWORD='postgres'
# database name
POSTGRES_DB='kashiwa'
# database connection URL (needed for Prisma)
DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}?schema=kashiwa"
KASHIWA_CONFIGURATION_FILE='configuration.yml' # or you can leave it empty, because configuration.yml is the default name of configuration file
NODE_ENV='production'
```
5. Edit the `configuration.yml` file as you wish. However, for security reasons we strongly recommend changing the values of `secure.user.salt-rounds` and `secure.session.secret`.
It is also highly recommended to add your domain to the list of allowed hosts in the `configuration.yml` in the parameter `http.cors.allowed-origins.default-preset` before the first startup
6. Run the database migration. Prisma will generate the client automatically:
```sh
$ npm run migrate:dev
```
7. Build the application:
```sh
$ npm run build
```
8. Congratulations, you’re ready to run the engine! Start it with:
```sh
$ npm run start:prod
```
Then go to [localhost:3000](http://localhost:3000).
Now you can go to [localhost:3000/kashiwa/auth/sign-up](http://localhost:3000/kashiwa/auth/sign-up) and create your first admin profile.
9. (Optionally) Now you can set up a reverse proxy for the website, instructions will not be given here.
## CORS Configuration
### What is CORS and why it is needed
CORS (Cross-Origin Resource Sharing) is a security mechanism implemented by web browsers that restricts web pages from making requests to a domain different from the one that served the web page.
In this project, the Nest.js imageboard is a monolithic website that:
- Serves static HTML pages pre-rendered with Pug.
- Provides AJAX-based functionality via REST API endpoints.
- Runs inside a Docker container.
Even though your frontend and backend are served from the same application, some features may require cross-origin requests.
CORS ensures that only requests from trusted origins are allowed to interact with the API, preventing unauthorized websites from making requests on behalf of your users.
### How to configure allowed origins
The list of allowed origins for CORS is managed through the administrative panel. Follow these steps to configure it:
1. Log in to your administrator account.
2. Go to the admin panel, in the section labeled "CORS settings".
3. Enter the desired origins in the form field. Each origin should be on a separate line (e.g., https://example.com).
4. Click Save to apply the changes.
Once saved, the new allowed origins are applied immediately to the application without restarting the server.
The CORS policy will restrict API access to the specified origins only.
## Supported markdown
The engine supports the following types of text markdown in user's message:
| Tag / Syntax | HTML Output | Description | Available when you disable the "Allow Markdown" option in the board settings. |
|--------------------------------|------------------------------------------|------------------------------------------|-------------------------------------------------------------------------------|
| `>text` (at beginning of line) | `>text` | Quote | ✔️ |
| `[spoiler]text[/spoiler]` | `text` | Spoiler | ❌ |
| `[code]text[/code]` | `
text
` | Code block | ❌ |
| `[s]text[/s]` | `text` | Strikethrough | ❌ |
| `[b]text[/b]` | `text` | Bold text | ❌ |
| `[i]text[/i]` | `text` | Italic text | ❌ |
| `>>123` | `` | Reply link to another comment | ✔️ |
| URL (http/https/ftp/irc) | `url` | Converts plain URLs into clickable links | ✔️ |
Administrators cannot write using markup under their account, however, they have full and unrestricted support for HTML markup (**please use this at your own risk**).
## Website Configuration params
The following is a list of application configuration parameters from the `configuration.yml` file.
| Parameter name | Type | Description | Remarks |
|--------------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `application.name` | `string` | The name of the application that will be displayed in the Swagger | |
| `application.description` | `string` | The description of the application that will be displayed in the Swagger | |
| `http.port` | `number` | Node.js HTTP server port on which the application will run | |
| `http.cors.allowed-origins.default-preset` | `Array` | A list of default domains (origins) allowed to access the API from browsers. Used to initialize the allowed CORS origins file on the first startup when no application volume exists. | It is recommended to change in before first startup |
| `file-storage.path` | `string` | The absolute path to the application where generated pages and downloaded files are stored. | |
| `secure.user.salt-rounds` | `number` | Number of password encryption iterations | It is recommended to increase in production |
| `secure.session.secret` | `string` | A secret for session encryption | It is recommended to change in production |
| `captcha.salt-rounds` | `number` | Number of captcha answer encryption iterations | |
| `captcha.size` | `number` | The length of the random captcha string | |
| `captcha.ignoreChars` | `string` | Filter out some characters from the captcha | |
| `captcha.noise` | `number` | Number of noise lines on captcha image | |
| `captcha.color` | `boolean` | If false, captcha will be black and white otherwise, it will be randomly colorized | |
| `captcha.background` | `string` | Background color of svg captcha image | |
| `whois.enabled` | `boolean` | Allow user country detection globally | |
| `whois.api.address` | `string` | API service address for determining the user's GeoIP | |
| `whois.api.method` | `string` | HTTP method for getting user information | |
| `whois.api.timeout` | `number` | GeoIP request timeout | |
## Supported file formats
Currently, the imageboard supports the following file types for uploading via the message sending interface:
- `image/png`
- `image/jpeg`
- `image/gif`
- `image/svg+xml`
- `image/webp`
- `video/mp4`
- `video/webm`
- `audio/aac`
- `audio/x-m4a`
- `audio/mpeg`
- `audio/ogg`
- `audio/flac`
- `application/x-bittorrent`
- `application/x-shockwave-flash`
- `application/x-7z-compressed`
In the settings for a specific board, you can set more specific file formats available for upload, limit the size of the uploaded file, or disable any file uploads altogether.
## Localization
### How I can translate the site to my language?
You now have an easier way to create your own localization for the Kashiwa engine.
An example file with all the localizable strings can be found at: `kashiwa/src/locale/locale-en.ts`
You can create another file with your own strings in your language based on the file `locale-en.ts` and connect it by importing it in the file `kashiwa/src/locale/locale.ts`
Alternatively, you can simply rewrite the existing strings in the `locale-en.ts` file in the language you want to translate the site into.
If desired, you can submit pull requests with your completed localizations.
## License
GPLV2 License
Because we believe that open source is important.