diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000000000000000000000000000000..a92706712ebf545a2ef9e73318719f3585ccbbcf --- /dev/null +++ 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/DEPLOY.md b/DEPLOY.md new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/README.md b/README.md index f1e87adc6f73e8fb3eb19d118b19fbd9d5c37899..87cab68db399429919ea13bef37cd5fd818d3a7a 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,29 @@ # Canvas -## Running via Docker Compose + + -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` +[![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 + +## Features + +## Roadmap + +## [Contributing](./CONTRIBUTING.md) + +[Report Vulnerabilities](./SECURITY.md) + +## [Deploying](./DEPLOY.md) + +## [Support Development](./SUPPORT.md) + +## Special Thanks + +## What is sc07? diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/doc/contributing/admin/architecture.md b/doc/contributing/admin/architecture.md new file mode 100644 index 0000000000000000000000000000000000000000..9a0a5d83273b9be92b074e885b9f686859a6de44 --- /dev/null +++ b/doc/contributing/admin/architecture.md @@ -0,0 +1,7 @@ +--- +title: Admin Architecture +--- + +``` +// TODO +``` diff --git a/doc/contributing/client/architecture.md b/doc/contributing/client/architecture.md new file mode 100644 index 0000000000000000000000000000000000000000..a8c7f4e406f41d59bb3887a40b6e3cc448581320 --- /dev/null +++ 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) diff --git a/doc/contributing/getting-started.md b/doc/contributing/getting-started.md new file mode 100644 index 0000000000000000000000000000000000000000..0b33d42ab7449b375646b96c8f8cc8e8c1ca513b --- /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. 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 + +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 0000000000000000000000000000000000000000..f7747cf77250da462acbdd89007dcb15e544d13b --- /dev/null +++ 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` diff --git a/doc/contributing/shared/architecture.md b/doc/contributing/shared/architecture.md new file mode 100644 index 0000000000000000000000000000000000000000..f6976c520a768252daca65c276129dd3ab125ea7 --- /dev/null +++ b/doc/contributing/shared/architecture.md @@ -0,0 +1,7 @@ +--- +title: Shared Architecture +--- + +``` +// TODO +``` diff --git a/packages/client/.env.example b/packages/client/.env.example new file mode 100644 index 0000000000000000000000000000000000000000..88a5716cfeac171dc7a1240f0105eb9a56d050bd --- /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 1891c6bdf9853b448805227190f084d8d48e5b85..0000000000000000000000000000000000000000 --- 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 73c1c5e76b46f59fe911ff51bae905b6454ce0d5..3eadd186b390cb3fc258cf473b358be3638f3df7 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 0000000000000000000000000000000000000000..057a469a197cba2758d1ebabc206878cfcbc3f60 --- /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 7059955605a9dcbf62643c9d781f85c424d643e7..82d4e3c0b57ab49fdb3cde41add6a9169ae49d4e 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",