Skip to content

Commit

Permalink
✨ Closes #327
Browse files Browse the repository at this point in the history
  • Loading branch information
@mawoka-myblock
mawoka-myblock committed Jan 3, 2024
1 parent 52724ca commit 06423c0
Show file tree
Hide file tree
Showing 3 changed files with 86 additions and 152 deletions.
2 changes: 2 additions & 0 deletions .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ repos:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
args:
- --allow-multiple-documents
# - id: check-added-large-files

- repo: https://github.com/psf/black
Expand Down
55 changes: 43 additions & 12 deletions docker-compose.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,21 +26,52 @@ services:
- redis

environment: &env_vars
DB_URL: "postgresql://postgres:classquiz@db:5432/classquiz"
REDIS: "redis://redis:6379/0?decode_responses=True"
# --- DON'T CHANGE FROM HERE ---
DB_URL: "postgresql://postgres:classquiz@db:5432/classquiz" # DON'T CHANGE
REDIS: "redis://redis:6379/0?decode_responses=True" # DON'T CHANGE
SECRET_KEY: "TOP_SECRET" # Don't change it manually, use the one-liner provided in the documentation
MAX_WORKERS: "1" # Very important and DON'T CHANGE
ACCESS_TOKEN_EXPIRE_MINUTES: 30 # DON'T CHANGE
MEILISEARCH_URL: "http://meilisearch:7700" # DON'T CHANGE
# -- DON'T CHANGE TILL HERE ---

# --- MAIL CONFIG ---
MAIL_PORT: "587"
MAIL_ADDRESS: "email@[email protected]"
MAIL_PASSWORD: "PASSWORT"
MAIL_USERNAME: "email@[email protected]"
MAIL_SERVER: "email@[email protected]"
MAX_WORKERS: "1" # Very important
MAIL_PORT: "587"
SECRET_KEY: "mysecretkey"
ACCESS_TOKEN_EXPIRE_MINUTES: 30
SKIP_EMAIL_VERIFICATION: True
HCAPTCHA_KEY: "HCAPTCHA_PRIVATE_KEY"
MEILISEARCH_URL: "http://meilisearch:7700"
STORAGE_BACKEND: "local"
STORAGE_PATH: "/app/data"
SKIP_EMAIL_VERIFICATION: "True" # Does the user have to confirm its email by clicking a link?

# --- EXTERNAL API CONFIG ---
# HCAPTCHA_KEY: "HCAPTCHA_PRIVATE_KEY"
# PIXABAY_API_KEY: "" # Get it from here: https://pixabay.com/api/docs/
# RECAPTCHA_KEY: "" Get it from Google for the Captcha.

# -- STORAGE CONFIG ---
STORAGE_BACKEND: "local" # Could also be s3
STORAGE_PATH: "/app/data" # When s3 is used, this isn't needed.
# If STORAGE_BACKEND is "s3"
#S3_ACCESS_KEY: "YOUR_ACCESS_KEY"
#S3_SECRET_KEY: "YOUR_SECRET_KEY"
#S3_BASE_URL: "YOUR_S3_BASE_URL"

# --- GOOGLE_AUTH ---
#GOOGLE_CLIENT_ID: "" # Your Google-Client ID, or leave it unset if you don't want it.
#GOOGLE_CLIENT_SECRET: "" # Your Google-Client Secret, or leave it unset if you don't want it.

# --- GITHUB_AUTH ---
#GITHUB_CLIENT_ID: "" # Your GitHub-Client ID, or leave it unset if you don't want it.
#GITHUB_CLIENT_SECRET: "" # Your GitHub-Client Secret, or leave it unset if you don't want it.

# --- Custom OpenID ---
#CUSTOM_OPENID_PROVIDER__CLIENT_ID: "" # Adjust if needed
#CUSTOM_OPENID_PROVIDER__CLIENT_SECRET: "" # Adjust if needed
#CUSTOM_OPENID_PROVIDER__SERVER_METADATA_URL: "/.well-known/openid-configuration" # Adjust if needed

volumes: # Only needed if you chose the "local" storage-backend
- ./uploads:/var/storage

redis:
image: redis:alpine
restart: always
Expand All @@ -66,7 +97,7 @@ services:
volumes:
- ./Caddyfile-docker:/etc/caddy/Caddyfile
ports:
- "8000:8080"
- "8000:8080" # The 8000 can be changed.
meilisearch:
image: getmeili/meilisearch:v0.28.0
restart: always
Expand Down
181 changes: 41 additions & 140 deletions frontend/src/routes/docs/self-host/+page.svelte
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ SPDX-FileCopyrightText: 2023 Marlon W (Mawoka)
SPDX-License-Identifier: MPL-2.0
-->
<script lang="ts">
<script lang='ts'>
import { onMount } from 'svelte';
import '$lib/hljs.css';
Expand All @@ -16,12 +16,12 @@ SPDX-License-Identifier: MPL-2.0
<svelte:head>
<title>ClassQuiz/docs - Self-Host</title>
<meta
name="description"
content="How to self-host ClassQuiz, the open-source quiz-application"
name='description'
content='How to self-host ClassQuiz, the open-source quiz-application'
/>
</svelte:head>
<article
class="prose prose-sm sm:prose lg:prose-lg xl:prose-xl mx-auto mt-10 prose-slate px-4 dark:prose-invert"
class='prose prose-sm sm:prose lg:prose-lg xl:prose-xl mx-auto mt-10 prose-slate px-4 dark:prose-invert'
>
<h1>Self-Hosting</h1>
<p>Since ClassQuiz is open-source, it can also be self-hosted.</p>
Expand All @@ -36,43 +36,43 @@ SPDX-License-Identifier: MPL-2.0
<h3>Software</h3>
<ul>
<li>
<a href="https://docker.com" target="_blank">Docker</a> (<a
href="https://docs.docker.com/compose/install/linux/"
target="_blank">Compose</a
>)
<a href='https://docker.com' target='_blank'>Docker</a> (<a
href='https://docs.docker.com/compose/install/linux/'
target='_blank'>Compose</a
>)
</li>
<li><a href="https://git-scm.com/" target="_blank">Git</a></li>
<li><a href='https://git-scm.com/' target='_blank'>Git</a></li>
<li>
A <a href="https://redis.com" target="_blank">Redis</a>-Server
A <a href='https://redis.com' target='_blank'>Redis</a>-Server
</li>
</ul>
<h3>3rd-Parties</h3>
<h4>Required</h4>
<ul>
<li><a href="https://hcaptcha.com">hCaptcha (Captcha)</a></li>
<li><a href="https://www.mapbox.com/">Mapbox (Maps)</a></li>
<li><a href='https://hcaptcha.com'>hCaptcha (Captcha)</a></li>
<li><a href='https://www.mapbox.com/'>Mapbox (Maps)</a></li>
</ul>
<h4>Optional</h4>
<ul>
<li><a href="https://sentry.io">Sentry (Error-Logging)</a></li>
<li><a href='https://sentry.io'>Sentry (Error-Logging)</a></li>
<li>
<a href="https://console.cloud.google.com/apis/dashboard"
>Google-Credentials (Sign-In)</a
<a href='https://console.cloud.google.com/apis/dashboard'
>Google-Credentials (Sign-In)</a
>
</li>
<li><a href="https://github.com/settings/developers">GitHub-Credentials (Sign-In)</a></li>
<li><a href='https://github.com/settings/developers'>GitHub-Credentials (Sign-In)</a></li>
</ul>

<h2>Installation</h2>
<p>At first, clone the repo:</p>

<pre><code class="language-bash"
>git clone https://github.com/mawoka-myblock/classquiz && cd ClassQuiz</code
></pre>
<pre><code class='language-bash'
>git clone https://github.com/mawoka-myblock/classquiz && cd ClassQuiz</code
></pre>
<p>
Now, you'll configure your frontend. You'll have to change the following in <code
>frontend/Dockerfile</code
>:
>frontend/Dockerfile</code
>:
</p>
<ul>
<li><code>VITE_MAPBOX_ACCESS_TOKEN</code>: A Mapbox-token which is optional.</li>
Expand All @@ -96,7 +96,7 @@ SPDX-License-Identifier: MPL-2.0
<h3>Storage Provider</h3>
<p>
You'll have to set up a storage provider for some pictures (these getting imported from
Kahoot!). For now, you can use <a href="https://min.io/" target="_blank">Minio (S3)</a> or
Kahoot!). For now, you can use <a href='https://min.io/' target='_blank'>Minio (S3)</a> or
the local filesystem. Please not that I'd recommend Minio for larger instances, since it can
be scaled and the media doesn't have to streamed through the (comparatively) slow ClassQuiz
server. Now, that you've decided on a storage backend, you can set the
Expand All @@ -120,16 +120,16 @@ SPDX-License-Identifier: MPL-2.0
Before you can start your stack, you have to set some environment-variables in your
<code>docker-compose.yml</code>.
</p>
<h3>GitHub/Google-Auth</h3>
<h3>GitHub/Google/OpenID-Auth</h3>
<p>
This step is purely optional, but it will enable users to log in using their
Google/GitHub-accounts.
</p>
<h4>Google</h4>
<p>
First, go to <a href="https://console.cloud.google.com/apis/dashboard"
>console.cloud.google.com/apis/dashboard</a
> and create a new project and select it. Then, go to the "OAuth consent screen" and set it up.
First, go to <a href='https://console.cloud.google.com/apis/dashboard'
>console.cloud.google.com/apis/dashboard</a
> and create a new project and select it. Then, go to the "OAuth consent screen" and set it up.
Next, go to the "Credentials"-tab and click on "Create Credentials" and create a new "OAuth Client
ID". This ID should be from the application-type "Web application". Afterwards, add a new "Authorised
JavaScript origin", which is just the base-domain (with https) of your ClassQuiz-installation.
Expand All @@ -140,129 +140,30 @@ SPDX-License-Identifier: MPL-2.0

<h4>GitHub</h4>
<p>
First, go to <a href="https://github.com/settings/developers"
>github.com/settings/developers</a
> and create a "new OAuth App". The "Authorization callback URL" has the following schema:
First, go to <a href='https://github.com/settings/developers'
>github.com/settings/developers</a
> and create a "new OAuth App". The "Authorization callback URL" has the following schema:
</p>
<pre><code>https://[BASE_URL]/api/v1/users/oauth/github/auth</code></pre>
<p>
That's it. Click on "Register application" and generate a new client secret and save it for
later, together with your client-id.
</p>
<h4>Custom OpenID auth</h4>
<p>A login using a custom OpenID provider is also possible. For that, adjust the settings in the docker-compose.yml
and configure the following scopes: "openid email profile". The follwoing redirect-url should be used:</p>
<pre><code>https://[BASE_URL]/api/v1/users/oauth/custom/auth</code></pre>
You'll also need to tell the frontend by editing the <code>frontend/Dockerfile</code>. Add the following line at the top, where all the other ENV's are as well:
<pre><code>ENV VITE_CUSTOM_OAUTH_NAME=[SOME_DISPLAY_NAME_FOR_THE_PROVIDER]</code></pre>

<h3>Docker-Compose File</h3>
<pre><code class="language-yaml"
>version: "3"

services:
frontend:
restart: always
build:
context: ./frontend
dockerfile: Dockerfile
depends_on:
- redis
- api
environment:
REDIS_URL: redis://redis:6379/0?decode_responses=True # don't change
API_URL: http://api:80 # don't change
api:
build: &build_cfg
context: .
dockerfile: Dockerfile
restart: &restart always
depends_on: &depends
- db
- redis

environment: &env_vars
ROOT_ADDRESS: "https://classquiz.de" # Base-URL (change it)
DB_URL: "postgresql://postgres:classquiz@db:5432/classquiz" # don't change
MAIL_ADDRESS: "[email protected]" # Email-Address (change it)
MAIL_PASSWORD: "MAIL_PASSWORD" # Email-Password (change it)
MAIL_USERNAME: "[email protected]" # Email-Username (change it)
MAIL_SERVER: "smtp.gmail.com" # SMTP-Server (change it)
MAIL_PORT: "587" # SMTP-Port
SKIP_EMAIL_VERIFICATION: True # Set this to skip sending emails
MAX_WORKERS: "1" # Very important and don't change it!
REDIS: "redis://redis:6379/0?decode_responses=True" # don't change
SECRET_KEY: "TOP_SECRET" # openssl rand -hex 32
MEILISEARCH_URL: "http://meilisearch:7700" # don't change
ACCESS_TOKEN_EXPIRE_MINUTES: 30 # don't change
HCAPTCHA_KEY: "" # Private hCaptcha key for verification (change it)
STORAGE_BACKEND: "local" # MUST BE EITHER "s3" OR "local"
FREE_STORAGE_LIMIT: "1074000000" # Free storage limit in bytes (default: 1GB)

# If STORAGE_BACKEND is "s3"
S3_ACCESS_KEY=YOUR_ACCESS_KEY
S3_SECRET_KEY=YOUR_SECRET_KEY
S3_BASE_URL=YOUR_S3_BASE_URL

# If STORAGE_BACKEND is "local"
STORAGE_PATH: "/var/storage"

# GOOGLE_AUTH
GOOGLE_CLIENT_ID: # Your Google-Client ID, or leave it unset if you don't want it.
GOOGLE_CLIENT_SECRET: # Your Google-Client Secret, or leave it unset if you don't want it.

# GITHUB_AUTH
GITHUB_CLIENT_ID: # Your GitHub-Client ID, or leave it unset if you don't want it.
GITHUB_CLIENT_SECRET: # Your GitHub-Client Secret, or leave it unset if you don't want it.

volumes: # Only needed if you chose the "local" storage-backend
- ./uploads:/var/storage

redis:
image: redis:alpine
restart: always
healthcheck:
test: [ "CMD", "redis-cli","ping" ]

db:
image: postgres:14-alpine
restart: always
healthcheck:
test: [ "CMD-SHELL", "pg_isready -U postgres" ]
interval: 5s
timeout: 5s
retries: 5
environment:
POSTGRES_PASSWORD: "classquiz"
POSTGRES_DB: "classquiz"

volumes:
- data:/var/lib/postgresql/data
proxy:
image: caddy:alpine
restart: always
volumes:
- ./Caddyfile-docker:/etc/caddy/Caddyfile
ports:
- "8000:8080" # Adjust the 8000 to your needs

meilisearch:
image: getmeili/meilisearch:latest
restart: always
environment:
MEILI_NO_ANALYTICS: true
volumes:
- meilisearch-data:/data.ms
worker:
build: *build_cfg
environment: *env_vars
restart: *restart
depends_on: *depends
command: arq classquiz.worker.WorkerSettings


volumes:
data:
meilisearch-data:
</code></pre>
<h3>Docker-Compose File</h3>
Please go through the <code>docker-compose.yml</code> thoroughly and fill out all the details, which should be
self-explanatory.
<p>Run the following command to generate and set the secret up automatically</p>
<pre><code class="language-bash"
>sed -i "s/TOP_SECRET/$(openssl rand -hex 32)/g" docker-compose.yml</code
></pre>
<pre><code class='language-bash'
>sed -i "s/TOP_SECRET/$(openssl rand -hex 32)/g" docker-compose.yml</code
></pre>
<p>Now build and deploy:</p>
<pre><code>docker compose build && docker compose up -d</code></pre>
<p><b>ClassQuiz needs HTTPS/SSL to work properly!</b></p>
Expand Down

0 comments on commit 06423c0

Please sign in to comment.