From 8b5844d0bf07318d9b3fb69dc6aff8061a92e20b Mon Sep 17 00:00:00 2001 From: Grant Date: Sun, 29 Dec 2024 19:26:55 -0700 Subject: [PATCH 01/10] add matrix, discord, lemmy, mastodon badges --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index f1e87ad..6220635 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,14 @@ # Canvas +![Matrix](https://img.shields.io/matrix/canvas%3Aaftermath.gg?style=flat&logo=matrix) +![Discord](https://img.shields.io/discord/1139660377370665102?style=flat&logo=discord) +![Lemmy](https://img.shields.io/lemmy/canvas%40toast.ooo?style=flat&logo=lemmy) +![Mastodon Follow](https://img.shields.io/mastodon/follow/110999563613177731?domain=https%3A%2F%2Fsocial.fediverse.events&style=flat&logo=mastodon&label=follow%20%40canvas%40fediverse.events&color=healthiness) + + + +Canvas is a real-time collaborative pixel canvas + ## Running via Docker Compose 1. Run `docker compose build` -- GitLab From 03a054556c09722d7ce8bf404909b55115382c39 Mon Sep 17 00:00:00 2001 From: Grant Date: Sun, 29 Dec 2024 22:12:11 -0700 Subject: [PATCH 02/10] add links to badges --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6220635..063e9a5 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Canvas -![Matrix](https://img.shields.io/matrix/canvas%3Aaftermath.gg?style=flat&logo=matrix) -![Discord](https://img.shields.io/discord/1139660377370665102?style=flat&logo=discord) -![Lemmy](https://img.shields.io/lemmy/canvas%40toast.ooo?style=flat&logo=lemmy) -![Mastodon Follow](https://img.shields.io/mastodon/follow/110999563613177731?domain=https%3A%2F%2Fsocial.fediverse.events&style=flat&logo=mastodon&label=follow%20%40canvas%40fediverse.events&color=healthiness) +[![Matrix](https://img.shields.io/matrix/canvas%3Aaftermath.gg?style=flat&logo=matrix)](https://matrix.to/#/#canvas:aftermath.gg) +[![Discord](https://img.shields.io/discord/1139660377370665102?style=flat&logo=discord)](https://discord.gg/mEUqXZw8kR) +[![Lemmy](https://img.shields.io/lemmy/canvas%40toast.ooo?style=flat&logo=lemmy)](https://toast.ooo/c/canvas) +[![Mastodon Follow](https://img.shields.io/mastodon/follow/110999563613177731?domain=https%3A%2F%2Fsocial.fediverse.events&style=flat&logo=mastodon&label=follow%20%40canvas%40fediverse.events&color=healthiness)](https://social.fediverse.events/@canvas) -- GitLab From 1a1980b93ce99b8241c4ec8dadb57a832c4e44e7 Mon Sep 17 00:00:00 2001 From: Grant Date: Sun, 29 Dec 2024 23:11:36 -0700 Subject: [PATCH 03/10] add placeholder sections --- README.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 063e9a5..edff9c1 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,20 @@ Canvas is a real-time collaborative pixel canvas -## Running via Docker Compose +## Motivation -1. Run `docker compose build` -2. (optional) Load default palette colors - Run `docker compose run --rm canvas npm run -w packages/server prisma:seed:palette` -3. Run `docker compose up -d` +## Features + +## Roadmap + +## [Contributing](./CONTRIBUTING.md) + +[Report Vulnerabilities](./SECURITY.md) + +## [Deploying](./DEPLOY.md) + +## [Support Development](./SUPPORT.md) + +## Special Thanks + +## What is sc07? -- GitLab From 4154ad603c0a92fdff7e217b2af5fa2bc50a855a Mon Sep 17 00:00:00 2001 From: Grant Date: Mon, 30 Dec 2024 22:12:52 -0700 Subject: [PATCH 04/10] placeholder files --- CONTRIBUTING.md | 0 DEPLOY.md | 0 SECURITY.md | 0 SUPPORT.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 DEPLOY.md create mode 100644 SECURITY.md create mode 100644 SUPPORT.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e69de29 diff --git a/DEPLOY.md b/DEPLOY.md new file mode 100644 index 0000000..e69de29 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..e69de29 diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..e69de29 -- GitLab From 429224867d7ea30dbc1f3e2190994e737d120411 Mon Sep 17 00:00:00 2001 From: Grant Date: Wed, 8 Jan 2025 23:08:03 -0700 Subject: [PATCH 05/10] donation badge --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index edff9c1..87cab68 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,13 @@ # Canvas + + + [![Matrix](https://img.shields.io/matrix/canvas%3Aaftermath.gg?style=flat&logo=matrix)](https://matrix.to/#/#canvas:aftermath.gg) [![Discord](https://img.shields.io/discord/1139660377370665102?style=flat&logo=discord)](https://discord.gg/mEUqXZw8kR) [![Lemmy](https://img.shields.io/lemmy/canvas%40toast.ooo?style=flat&logo=lemmy)](https://toast.ooo/c/canvas) [![Mastodon Follow](https://img.shields.io/mastodon/follow/110999563613177731?domain=https%3A%2F%2Fsocial.fediverse.events&style=flat&logo=mastodon&label=follow%20%40canvas%40fediverse.events&color=healthiness)](https://social.fediverse.events/@canvas) - - Canvas is a real-time collaborative pixel canvas ## Motivation -- GitLab From 2eb669e1ee000095c0be75b6df13f22938a40264 Mon Sep 17 00:00:00 2001 From: Grant Date: Thu, 16 Jan 2025 22:28:47 -0700 Subject: [PATCH 06/10] [wip] --- CONTRIBUTING.md | 19 ++++++++ doc/contributing/admin/architecture.md | 0 doc/contributing/client/architecture.md | 0 doc/contributing/getting-started.md | 63 +++++++++++++++++++++++++ doc/contributing/server/architecture.md | 0 doc/contributing/shared/architecture.md | 0 packages/client/.env.example | 30 ++++++++++++ packages/client/dev.env.example | 8 ---- packages/client/vite.config.js | 6 ++- packages/server/.env.example | 49 +++++++++++++++++++ packages/server/package.json | 2 +- 11 files changed, 166 insertions(+), 11 deletions(-) create mode 100644 doc/contributing/admin/architecture.md create mode 100644 doc/contributing/client/architecture.md create mode 100644 doc/contributing/getting-started.md create mode 100644 doc/contributing/server/architecture.md create mode 100644 doc/contributing/shared/architecture.md create mode 100644 packages/client/.env.example delete mode 100644 packages/client/dev.env.example create mode 100644 packages/server/.env.example diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e69de29..a927067 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -0,0 +1,19 @@ +# Contributing + +Canvas is split into a couple different pieces, that being the backend, frontend, admin frontend & shared code. + +## Backend + +**Location:** `/packages/server` + +## Frontend + +**Location:** `/packages/client` + +## Admin Frontend + +**Location:** `/packages/admin` + +## Shared + +**Location:** `/packages/lib` diff --git a/doc/contributing/admin/architecture.md b/doc/contributing/admin/architecture.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/contributing/client/architecture.md b/doc/contributing/client/architecture.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/contributing/getting-started.md b/doc/contributing/getting-started.md new file mode 100644 index 0000000..4307884 --- /dev/null +++ b/doc/contributing/getting-started.md @@ -0,0 +1,63 @@ +--- +title: Getting Started +--- + +Interested in contributing to Canvas? Great! + +# Giving feedback + +Feedback is greatly appreciated and can be given in many places: + +- In [#canvas-meta:aftermath.gg](<(https://matrix.to/#/#canvas-meta:aftermath.gg)>) on Matrix [![Matrix](https://img.shields.io/matrix/canvas-meta%3Aaftermath.gg?style=flat&logo=matrix)](https://matrix.to/#/#canvas-meta:aftermath.gg) +- In #meta on Discord [![Discord](https://img.shields.io/discord/1139660377370665102?style=flat&logo=discord)](https://discord.gg/mEUqXZw8kR) +- In c/canvas@toast.ooo on Lemmy [![Lemmy](https://img.shields.io/lemmy/canvas%40toast.ooo?style=flat&logo=lemmy)](https://toast.ooo/c/canvas) +- By tagging @canvas@fediverse.events on Mastodon [![Mastodon Follow](https://img.shields.io/mastodon/follow/110999563613177731?domain=https%3A%2F%2Fsocial.fediverse.events&style=flat&logo=mastodon&label=follow%20%40canvas%40fediverse.events&color=healthiness)](https://social.fediverse.events/@canvas) + +# Development + +The project is setup as a monorepo, with the frontend, backend and admin interface all in one place. + +## Prerequisites + +- [Docker](https://www.docker.com/) +- [fediverse-auth](https://sc07.dev/sc07/fediverse-auth) +- git +- Nodejs (unless if nvm is installed) +- (Optional, but prefered) [nvm](https://nvm.sh) (Node Version Manager) - Manages & installs nodejs versions + +## Quick start + +1. `nvm use` +1. copy `packages/client/.env.example` to `packages/client/.env.local` and modify (if needed) +1. copy `packages/server/.env.example` to `packages/server/.env` and modify +1. ensure fediverse-auth is running +1. `npm install --include=dev` +1. `npm run dev:server` +1. `npm run dev:client` + +## Architecture + +Directory layouts and design architecture can be found here + +- [packages/server](./server/architecture.md) +- [packages/client](./client/architecture.md) +- [packages/lib](./shared/architecture.md) +- [packages/admin](./admin/architecture.md) + +## Building + +### Quick production environment + +Building is done via Docker and a quick production environment can be brought up using the `docker-compose.yml` + +`docker compose up -d --build` + +### Docker image + +This will build a Docker image that contains the server, client & admin UI + +`docker build .` + +## Contributing upstream + +Canvas is hosted on [the sc07 GitLab](https://sc07.dev/sc07/canvas), and at time of writing does require registrations to be manually approved. Applications should be approved within a day, but feel free to send a message in the Discord or Matrix space to ensure it gets approved. diff --git a/doc/contributing/server/architecture.md b/doc/contributing/server/architecture.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/contributing/shared/architecture.md b/doc/contributing/shared/architecture.md new file mode 100644 index 0000000..e69de29 diff --git a/packages/client/.env.example b/packages/client/.env.example new file mode 100644 index 0000000..88a5716 --- /dev/null +++ b/packages/client/.env.example @@ -0,0 +1,30 @@ +############################################################# +# # +# CANVAS FRONTEND ENVIRONMENT # +# # +# This file must be copied to `.env.local` # +# for Vite to pick it up # +# # +############################################################# + +# if the development server is on a different port, you can change this here +# the default is localhost:3000 if not specified +# this is never used at build time +# +# BACKEND_HOST=localhost:3000 + +# --- Sentry Settings --- +# see /doc/deploy/sentry.md + +# Sentry DSN, used at build time & development +# if not specified the Sentry client is never initiated +# +# SENTRY_DSN=https://example@sentry.local/0 + +# Sourcemap pushing settings +# See /doc/deploy/sentry.md +# +# SENTRY_URL= +# SENTRY_ORG= +# SENTRY_PROJECT= +# SENTRY_AUTH_TOKEN= \ No newline at end of file diff --git a/packages/client/dev.env.example b/packages/client/dev.env.example deleted file mode 100644 index 1891c6b..0000000 --- a/packages/client/dev.env.example +++ /dev/null @@ -1,8 +0,0 @@ -# where the backend is located -VITE_API_HOST=http://localhost:3000 - -# what homeserver hosts the matrix users -VITE_MATRIX_HOST=aftermath.gg - -# what hostname does the element instance run on -VITE_ELEMENT_HOST=https://chat.fediverse.events \ No newline at end of file diff --git a/packages/client/vite.config.js b/packages/client/vite.config.js index 73c1c5e..3eadd18 100644 --- a/packages/client/vite.config.js +++ b/packages/client/vite.config.js @@ -11,6 +11,8 @@ const commitHash = child export default defineConfig(({ mode }) => { process.env = { ...process.env, ...loadEnv(mode, process.cwd(), "") }; + const BACKEND_HOST = process.env.BACKEND_HOST || "localhost:3000"; + return { root: "src", envDir: "..", @@ -31,9 +33,9 @@ export default defineConfig(({ mode }) => { }, server: { proxy: { - "/api": "http://localhost:3000", + "/api": "http://" + BACKEND_HOST, "/socket.io": { - target: "ws://localhost:3000", + target: "ws://" + BACKEND_HOST, ws: true, }, }, diff --git a/packages/server/.env.example b/packages/server/.env.example new file mode 100644 index 0000000..057a469 --- /dev/null +++ b/packages/server/.env.example @@ -0,0 +1,49 @@ +############################################################# +# # +# CANVAS BACKEND ENVIRONMENT # +# # +# This file must be copied to `.env` # +# # +############################################################# + +# Full postgres database URI +# Must also include database name at the end +DATABASE_URL=postgres://canvas@127.0.0.1:5432/canvas + +# Redis URI +REDIS_HOST=redis://localhost +# Session prefix in Redis +REDIS_SESSION_PREFIX=canvas_session: + +NODE_ENV=development +LOG_LEVEL=debug +PORT=3000 + +SESSION_SECRET=SomeRandomTextHere + +# Prometheus authorization token for /metrics +PROMETHEUS_TOKEN=token + +# Host for callback redirect +# Default is the Vite default +OIDC_CALLBACK_HOST=http://localhost:5173 +# Fediverse-auth host +AUTH_ENDPOINT=http://fedi-auth +AUTH_CLIENT=client_id_here +AUTH_SECRET=client_secret_here + +# If these are set to absolute paths, they will be served by the main server +# Primarily used during deployment +# SERVE_CLIENT= +# SERVE_ADMIN= + +### Matrix/chat ### +MATRIX_HOMESERVER=matrix.org +ELEMENT_HOST=https://element.io +MATRIX_GENERAL_ALIAS=%23canvas-general:aftermath.gg + +### Sentry ### +# See /doc/deploy/sentry.md + +# SENTRY_DSN=https://example@sentry.local/0 +# SENTRY_TUNNEL_PROJECT_IDS=1 \ No newline at end of file diff --git a/packages/server/package.json b/packages/server/package.json index 38c7b77..1b9c00e 100644 --- a/packages/server/package.json +++ b/packages/server/package.json @@ -2,7 +2,7 @@ "name": "@sc07-canvas/server", "version": "1.0.0", "scripts": { - "dev": "DOTENV_CONFIG_PATH=.env.local tsx watch -r dotenv/config src/index.ts", + "dev": "tsx watch -r dotenv/config src/index.ts", "start": "node --enable-source-maps dist/index.js", "profiler": "node --inspect=0.0.0.0:9229 --enable-source-maps dist/index.js", "build": "tsc", -- GitLab From af7584094fe58ebc1ef5a6a6eb99e694ec6892a8 Mon Sep 17 00:00:00 2001 From: Grant <3380410-grahhnt@users.noreply.gitlab.com> Date: Wed, 29 Jan 2025 21:19:06 -0700 Subject: [PATCH 07/10] clean up quick start --- doc/contributing/getting-started.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/contributing/getting-started.md b/doc/contributing/getting-started.md index 4307884..0b33d42 100644 --- a/doc/contributing/getting-started.md +++ b/doc/contributing/getting-started.md @@ -27,13 +27,13 @@ The project is setup as a monorepo, with the frontend, backend and admin interfa ## Quick start -1. `nvm use` -1. copy `packages/client/.env.example` to `packages/client/.env.local` and modify (if needed) -1. copy `packages/server/.env.example` to `packages/server/.env` and modify -1. ensure fediverse-auth is running -1. `npm install --include=dev` -1. `npm run dev:server` -1. `npm run dev:client` +1. Use the node version the project is built using (run `nvm use` in the root or view `/.nvmrc` for the version) +2. Copy `packages/client/.env.example` to `packages/client/.env.local` and modify +3. Copy `packages/server/.env.example` to `packages/server/.env.local` and modify +4. Start fediverse-auth +5. Install all dependencies (`npm install --include=dev`) +6. Start the server: `npm run dev:server` +7. Start the client: `npm run dev:client` ## Architecture -- GitLab From f669126c701230c52fd73f7f071336fb84f90934 Mon Sep 17 00:00:00 2001 From: Grant <3380410-grahhnt@users.noreply.gitlab.com> Date: Wed, 29 Jan 2025 21:31:39 -0700 Subject: [PATCH 08/10] add server architecture --- doc/contributing/server/architecture.md | 38 +++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/doc/contributing/server/architecture.md b/doc/contributing/server/architecture.md index e69de29..f7747cf 100644 --- a/doc/contributing/server/architecture.md +++ b/doc/contributing/server/architecture.md @@ -0,0 +1,38 @@ +--- +title: Server Architecture +--- + +# /packages/server + +## src/api/ + +Contains Express Router() instances for API endpoints (loaded by `lib/Express.ts`) + +## src/lib/ + +Contains majority of modules + +## src/models/ + +Wrappers for database objects to add extra utilities + +## src/tools/ + +Scripts that are compiled to `.js` at build time and are accessable by `npm run tool` (see [tool.sh](#toolsh)) + +## src/workers/ + +Houses worker source files that are run by nodejs worker threads + +## src/jobs/ + +Contains automated jobs + +## tool.sh + +Utility used by the `tool` script, used to execute tools from `src/tools/` based on runtime (eg. development or production) + +> `npm run tool init_settings` will run one of the following: +> +> - if `NODE_ENV` is `production`: `dist/tools/init_settings.js` +> - else: `src/tools/init_settings.ts` -- GitLab From da5162e0fad7cdd87d8b7ca25f86172411efb8a5 Mon Sep 17 00:00:00 2001 From: Grant <3380410-grahhnt@users.noreply.gitlab.com> Date: Wed, 29 Jan 2025 22:04:06 -0700 Subject: [PATCH 09/10] add client architecture --- doc/contributing/client/architecture.md | 53 +++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/doc/contributing/client/architecture.md b/doc/contributing/client/architecture.md index e69de29..a8c7f4e 100644 --- a/doc/contributing/client/architecture.md +++ b/doc/contributing/client/architecture.md @@ -0,0 +1,53 @@ +--- +title: Client Architecture +--- + +# Theming + +- [tailwindcss](https://tailwindcss.com/) +- Component library: [HeroUI](https://www.heroui.com/docs/components) (formerly NextUI) +- Icon library: [FontAwesome](https://fontawesome.com/icons) [@icons-pack/react-simple-icons](https://www.npmjs.com/package/@icons-pack/react-simple-icons) +- [framer-motion](https://motion.dev/docs) +- (Discouraged) SCSS is loaded and the entrypoint is `src/style.scss` + +# Networking + +Networking is done via REST & WebSocket + +## REST + +The main use for REST is for non-immediate actions (like moderation or profile changes) + +The endpoints are exposed in `/packages/server/src/api/` + +## WebSocket + +Executed via socket.io and client-side communications are handled in `packages/client/src/lib/network.ts` + +Event names & data are specified in `/packages/lib/src/net.ts` to be shared by client & server + +# File Structure (/packages/client) + +## src/components/ + +Houses all the React elements + +- Generally one file is one component +- Components that contain multiple sub-components should be placed in their own folder (eg all chat components are in their own folder) + +## src/contexts/ + +Every context should be placed in this folder + +## src/lib/ + +Every component that isn't a React component + +## src/worker/ + +Files that are loaded as ServiceWorkers + +- Files should end with `.worker.ts` in this folder +- ServiceWorkers are loaded at runtime via adding `?worker` to the import line + +> See: [vite.dev](https://vite.dev/guide/features.html#web-workers) -- GitLab From dae48116291ec53c874c2de77a85bfc2f4f24fd5 Mon Sep 17 00:00:00 2001 From: Grant <3380410-grahhnt@users.noreply.gitlab.com> Date: Wed, 29 Jan 2025 22:32:43 -0700 Subject: [PATCH 10/10] add placeholders for shared & admin architecture --- doc/contributing/admin/architecture.md | 7 +++++++ doc/contributing/shared/architecture.md | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/doc/contributing/admin/architecture.md b/doc/contributing/admin/architecture.md index e69de29..9a0a5d8 100644 --- a/doc/contributing/admin/architecture.md +++ b/doc/contributing/admin/architecture.md @@ -0,0 +1,7 @@ +--- +title: Admin Architecture +--- + +``` +// TODO +``` diff --git a/doc/contributing/shared/architecture.md b/doc/contributing/shared/architecture.md index e69de29..f6976c5 100644 --- a/doc/contributing/shared/architecture.md +++ b/doc/contributing/shared/architecture.md @@ -0,0 +1,7 @@ +--- +title: Shared Architecture +--- + +``` +// TODO +``` -- GitLab