diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e9a9a059..2c5f3a96 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,21 @@ # Contributing to Lysand + Thank you for your interest in contributing to Lysand! We welcome contributions from everyone, regardless of their level of experience or expertise. +# Tech Stack + +Lysand is built using the following technologies: + +- [Bun](https://bun.sh) - A JavaScript runtime similar to Node.js, but improved +- [PostgreSQL](https://www.postgresql.org/) - A relational database + - [`pg_uuidv7`](https://github.com/fboulnois/pg_uuidv7) - A PostgreSQL extension that provides a UUIDv7 data type +- [UnoCSS](https://unocss.dev) - A utility-first CSS framework, used for the login page +- [Docker](https://www.docker.com/) - A containerization platform, used for development and deployment +- [Sharp](https://sharp.pixelplumbing.com/) - An image processing library, used for fast image resizing and converting +- [TypeScript](https://www.typescriptlang.org/) - A typed superset of JavaScript +- [ESLint](https://eslint.org/) - A JavaScript linter +- [Prettier](https://prettier.io/) - A code formatter + ## Getting Started To get started, please follow these steps: @@ -9,41 +24,53 @@ To get started, please follow these steps: ```sh curl -fsSL https://bun.sh/install | bash ``` -3. Run `bun install` in the project directory to install the dependencies -```sh +1. Clone this repository + +```bash +git clone https://github.com/lysand-org/lysand.git +``` + +2. Install the dependencies + +```bash bun install ``` -> You will need a running PostgreSQL database for the next step -> If you don't have a running PostgreSQL instance, you can use the following `docker-compose.yml` file to start one: -> ```yaml ->services: -> db: -> image: postgres:13-alpine -> restart: always -> init: true -> environment: { -> POSTGRES_USER: fediproject, -> POSTGRES_PASSWORD: fediproject, -> POSTGRES_DB: fediproject -> } -> ports: -> - 5432:5432 -> volumes: -> - ./data:/var/lib/postgresql/data -> ``` +3. Set up a PostgreSQL database, using the `pg_uuidv7` extension -4. Copy the `config/config.example.toml` file to `config/config.toml` and change the database connection values to your own Postgres instance -> For the example above, the values would be: -> ```toml -> [database] -> host = "localhost" -> port = 5432 -> username = "fediproject" -> password = "fediproject" -> database = "fediproject" -> ``` -5. Fill in the rest of the config file with your own configuration (you can leave most things to the default) +You may use the following [Dockerfile](Postgres.Dockerfile) to set it up: + +```Dockerfile +# Use the latest Postgres Docker image based on Alpine +FROM postgres:alpine + +# Set working directory +WORKDIR /usr/src/app + +# Install curl +RUN apk add --no-cache curl + +RUN cd "$(mktemp -d)" \ + && curl -LO "https://github.com/fboulnois/pg_uuidv7/releases/download/v1.3.0/{pg_uuidv7.tar.gz,SHA256SUMS}" \ + && tar xf pg_uuidv7.tar.gz \ + && sha256sum -c SHA256SUMS \ + && PG_MAJOR=$(pg_config --version | sed 's/^.* \([0-9]\{1,\}\).*$/\1/') \ + && cp "$PG_MAJOR/pg_uuidv7.so" "$(pg_config --pkglibdir)" \ + && cp sql/pg_uuidv7--1.3.sql pg_uuidv7.control "$(pg_config --sharedir)/extension" +# Add a script to run the CREATE EXTENSION command +RUN echo '#!/bin/sh\npsql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "CREATE EXTENSION pg_uuidv7;"' > /docker-entrypoint-initdb.d/init.sh + +# Make the entrypoint script executable +RUN chmod +x /docker-entrypoint-initdb.d/init.sh +``` + +4. Copy the `config.toml.example` file to `config.toml` and fill in the values (you can leave most things to the default, but you will need to configure things such as the database connection) + +5. Run migrations: + +```bash +bun migrate +``` ## Testing your changes @@ -61,4 +88,52 @@ To run the tests, run: bun test ``` -The tests are located in the `tests/` directory and follow a Jest-like syntax. \ No newline at end of file +The tests are located in the `tests/` directory and follow a Jest-like syntax. The server must be started with `bun dev` before running the tests. + +## Code style + +We use ESLint and Prettier to enforce a consistent code style. To check if your code is compliant, run: +```sh +bun lint +``` + +To automatically fix the issues, run: +```sh +bun lint --fix +``` + +You should have the [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) extensions installed in VSCode, if you use it. From the ESLint extension, you can automatically fix the issues with `Ctrl+Shift+P` and `ESLint: Fix all auto-fixable Problems`. + +ESLint and Prettier are also integrated in the CI pipeline, so your code will be automatically checked when you push it. If the pipeline fails, you will need to fix the issues before your pull request can be merged. + +Code style such as brackets, spaces/tabs, etc are enforced by Prettier's ESLint plugin. You can find the simple configuration in the `.prettierrc` file. + +### ESLint rules + +ESLint errors should not be ignored, except if they are false positives, in which case you can use a comment to disable the rule for the line or the file. If you need to disable a rule, please add a comment explaining why. + +TypeScript errors should be ignored with `// @ts-expect-error` comments, as well as with a reason for being ignored. + +### Commit messages + +We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for our commit messages. This allows us to automatically generate the changelog and the version number. + +### Pull requests + +When you are done with your changes, you can open a pull request. Please make sure that your code is compliant with the code style and that the tests pass before opening a pull request. + +### Writing tests + +We use Bun's integrated testing system to write tests. You can find more information about it [here](https://bun.sh/docs/cli/test). It uses a Jest-like syntax. + +Tests **must** be written for all API routes and all functions that are not trivial. If you are not sure whether you should write a test for something, you probably should. + +To help with the creation of tests, you may find [GitHub Copilot](https://copilot.github.com/) useful (or some of its free alternatives like [Codeium](https://codeium.com/)) + +### Writing documentation + +Documentation for the Lysand protocol is available on [lysand.org](https://lysand.org/). If you are thinking of modifying the protocol, please make sure to send a pull request over there to get it approved and merged before you send your pull request here. + +# License + +Lysand is licensed under the [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) license. By contributing to Lysand, you agree to license your contributions under the same license. \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..b8d0feda --- /dev/null +++ b/Dockerfile @@ -0,0 +1,35 @@ +# use the official Bun image +# see all versions at https://hub.docker.com/r/oven/bun/tags +FROM oven/bun:1.0.13-alpine as base +WORKDIR /usr/src/app + +# install dependencies into temp directory +# this will cache them and speed up future builds +FROM base AS install +RUN mkdir -p /temp/dev +COPY package.json bun.lockb /temp/dev/ +RUN cd /temp/dev && bun install --frozen-lockfile + +# install with --production (exclude devDependencies) +RUN mkdir -p /temp/prod +COPY package.json bun.lockb /temp/prod/ +RUN cd /temp/prod && bun install --frozen-lockfile --production + +# copy node_modules from temp directory +# then copy all (non-ignored) project files into the image +FROM install AS prerelease +COPY --from=install /temp/dev/node_modules node_modules +COPY . . + +# copy production dependencies and source code into final image +FROM base AS release + +# Create app directory +RUN mkdir -p /app +COPY --from=install /temp/prod/node_modules /app/node_modules +COPY --from=prerelease /usr/src/app /app + + +# run the app +USER bun +ENTRYPOINT [ "bun", "run", "index.ts" ] diff --git a/README.md b/README.md index b1349172..8155d2bf 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# Lysand +

+ Lysand Logo +

![Postgres](https://img.shields.io/badge/postgres-%23316192.svg?style=for-the-badge&logo=postgresql&logoColor=white) ![Bun](https://img.shields.io/badge/Bun-%23000000.svg?style=for-the-badge&logo=bun&logoColor=white) ![VS Code Insiders](https://img.shields.io/badge/VS%20Code%20Insiders-35b393.svg?style=for-the-badge&logo=visual-studio-code&logoColor=white) ![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white) ![Linux](https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black) ![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge&logo=docker&logoColor=white) ![ESLint](https://img.shields.io/badge/ESLint-4B3263?style=for-the-badge&logo=eslint&logoColor=white) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa?style=for-the-badge)](code_of_conduct.md) @@ -11,6 +13,20 @@ This project aims to be a fully featured social network, with a focus on privacy > **Note:** This project is not affiliated with Mastodon or Pleroma, and is not a fork of either project. It is a new project built from the ground up. +## Features + +- [x] Inbound federation +- [x] S3 or local media storage +- [x] Deduplication of uploaded files +- [x] Federation limits +- [x] Configurable defaults +- [x] Full regex-based filters for posts, users and media +- [x] Custom emoji support +- [x] Automatic image conversion to WebP or other formats +- [ ] Moderation tools +- [ ] Full Mastodon API support +- [ ] Outbound federation + ## How do I run it? ### Requirements @@ -26,7 +42,7 @@ This project aims to be a fully featured social network, with a focus on privacy 1. Clone this repository ```bash -git clone https://github.com/CPlusPatch/lysand.git +git clone https://github.com/lysand-org/lysand.git ``` 2. Install the dependencies @@ -35,10 +51,42 @@ git clone https://github.com/CPlusPatch/lysand.git bun install ``` -3. Set up a PostgreSQL database +3. Set up a PostgreSQL database, using the `pg_uuidv7` extension + +You may use the following [Dockerfile](Postgres.Dockerfile) to set it up: + +```Dockerfile +# Use the latest Postgres Docker image based on Alpine +FROM postgres:alpine + +# Set working directory +WORKDIR /usr/src/app + +# Install curl +RUN apk add --no-cache curl + +RUN cd "$(mktemp -d)" \ + && curl -LO "https://github.com/fboulnois/pg_uuidv7/releases/download/v1.3.0/{pg_uuidv7.tar.gz,SHA256SUMS}" \ + && tar xf pg_uuidv7.tar.gz \ + && sha256sum -c SHA256SUMS \ + && PG_MAJOR=$(pg_config --version | sed 's/^.* \([0-9]\{1,\}\).*$/\1/') \ + && cp "$PG_MAJOR/pg_uuidv7.so" "$(pg_config --pkglibdir)" \ + && cp sql/pg_uuidv7--1.3.sql pg_uuidv7.control "$(pg_config --sharedir)/extension" +# Add a script to run the CREATE EXTENSION command +RUN echo '#!/bin/sh\npsql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "CREATE EXTENSION pg_uuidv7;"' > /docker-entrypoint-initdb.d/init.sh + +# Make the entrypoint script executable +RUN chmod +x /docker-entrypoint-initdb.d/init.sh +``` 4. Copy the `config.toml.example` file to `config.toml` and fill in the values (you can leave most things to the default, but you will need to configure things such as the database connection) +5. Run migrations: + +```bash +bun migrate +``` + ### Running To run the server, simply run the following command: diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 00000000..a03827a5 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,12 @@ +version: '3' +services: + lysand: + build: + context: . + dockerfile: Dockerfile + ports: + - 8080:8080 + container_name: lysand + volumes: + - ./logs:/app/logs + - ./config:/app/config diff --git a/package.json b/package.json index 7e024233..10dbb32b 100644 --- a/package.json +++ b/package.json @@ -33,7 +33,9 @@ "private": true, "scripts": { "dev": "bun run index.ts", - "start": "bun run index.ts" + "start": "bun run index.ts", + "migrate-dev": "bunx prisma migrate dev", + "migrate": "bunx prisma migrate deploy" }, "trustedDependencies": [ "sharp",