learnhouse/docs
1
0
Fork 0
mirror of https://github.com/learnhouse/docs.git synced 2026-02-18 00:07:39 +01:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add a better self hosting guide + Dev env guide

Browse Source
This commit is contained in:
swve
2024-04-21 19:05:34 +02:00
parent fa4d96c044
commit ed8e9a5d08
7 changed files with 243 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
pages/_meta.json
View File

@@ -5,12 +5,17 @@
},
"index": "Introduction",
"features": "Features",
"-- Self Hosting": {
"type": "separator",
"title": "Self Hosting"
},
"self-hosting": "Get started",
"-- Developers": {
"type": "separator",
"title": "Developers"
},
"setup-dev-environment": "Quick Start",
"concepts": "Concepts",
"self-hosting": "Self Hosting"
"setup-dev-environment": "Dev Environment",
"concepts": "Concepts"
}

2
pages/self-hosting/_meta.json
View File

@@ -1,8 +1,8 @@
{
"overview": "Overview",
"hosting-guide": "Self Hosting Guide",
"configuration": "Configuration",
"organization-hosting-modes": "Organization Hosting Modes",
"docker-and-kube": "Docker and Kubernetes",
"ai": "AI",
"content-storage": "Content Storage"
}

48
pages/self-hosting/configuration.mdx
View File

@@ -4,27 +4,50 @@ import { Callout } from 'nextra/components'
For self hosted LearnHouse users, a custom configuration file can be used to suit your needs.
## Backend config file
Here is an example of the `config.yaml` file :
```json filename="config.yaml" copy
```yaml filename="config.yaml" copy
site_name: LearnHouse
site_description: LearnHouse is an open-source platform tailored for learning experiences.
contact_email: hi@learnhouse.app
general:
development_mode: false
install_mode: false
security:
auth_jwt_secret_key: secret
hosting_config:
domain: learnhouse.app
ssl: true
port: 1338
allowed_origins:
- http://localhost:3000
- http://localhost:3001
cookies_config:
domain: ".localhost"
allowed_regexp: '\b((?:https?://)[^\s/$.?#].[^\s]*)\b'
content_delivery:
type: "filesystem" # "filesystem" or "s3api"
s3api:
bucket_name: ""
endpoint_url: ""
mailing_config:
resend_api_key: ""
system_email_adress: ""
database_config:
sql_connection_string: postgresql://learnhouse:learnhouse@postgresql:5432/learnhouse
sql_connection_string: postgresql://learnhouse:learnhouse@localhost:5432/learnhouse
redis_config:
redis_connection_string: redis://localhost:6379/learnhouse
```
You can also use a `.env` file to configure your backend.
If an environment variable is set, it will override the value in the `config.yaml` file, here is an example of the `.env` file :
<Callout>
If an environment variable is set, it will override the value in the `config.yaml` file
</Callout>
```env filename=".env" copy
LEARNHOUSE_SITE_NAME=LearnHouse
@@ -38,7 +61,6 @@ LEARNHOUSE_COOKIE_DOMAIN=.localhost
LEARNHOUSE_ALLOWED_REGEXP=\b((?:https?://)[^\s/$.?#].[^\s]*)\b
LEARNHOUSE_SELF_HOSTED=false
LEARNHOUSE_SQL_CONNECTION_STRING=postgresql://learnhouse:learnhouse@postgresql:5432/learnhouse
```
@@ -92,7 +114,7 @@ You can add a `.` before your domain, here it would be `.domain.app`
### Database Config
#### PostgreSQL Database config
#### PostgreSQL Connection string
<Callout type="info">
As of December 2023, we've transitioned our database structure to PostgreSQL.
@@ -100,6 +122,22 @@ You can add a `.` before your domain, here it would be `.domain.app`
Your PostgreSQL Database connection string
### Redis Config
#### Redis connection string
Your Redis Database connection string
### Mailing Config
#### Resend API Key
Your Resend API Key
#### System Email Address
Your System Email Address
## Frontend config file
You can also configure your frontend by creating a `.env` file in the `apps/web` folder.

43
pages/self-hosting/docker-and-kube.mdx
View File

@@ -1,43 +0,0 @@
import { Callout } from 'nextra-theme-docs'
import { Steps } from 'nextra-theme-docs'
# Docker and Kubernetes
<Callout type="warning" >
LearnHouse is still in **alpha** and is not yet ready for production use.
</Callout>
## Docker
<Steps>
### Install Docker
To install Docker, follow the instructions for your operating system on the [Docker website](https://docs.docker.com/get-docker/).
### Download the LearnHouse repository
```bash copy
git clone https://github.com/learnhouse/learnhouse
```
#### Go to the directory
```shell copy
cd learnhouse
```
### Build and run the backend and frontend docker images
```shell copy
docker-compose up -d
```
</Steps>
## Kubernetes
<Callout type="info" >
We're still working on a kubernetes deployment guide.
</Callout>

107
pages/self-hosting/hosting-guide.mdx Normal file
View File

@@ -0,0 +1,107 @@
import { Callout } from 'nextra-theme-docs'
import { Steps } from 'nextra-theme-docs'
# Self hosting guide
We use Docker & Docker compose to run LearnHouse, this makes it easy to run the application on any machine that has Docker installed.
Tested on :
- macOS Sonoma
- Ubuntu 23.04 Lunar lobster
- (Need testers on Windows)
## Prerequisites
- [Docker](https://docs.docker.com/get-docker/)
## Step by step
<Steps>
### Install Docker
To install Docker, follow the instructions for your operating system on the [Docker website](https://docs.docker.com/get-docker/).
### Download the LearnHouse repository
```bash copy
git clone https://github.com/learnhouse/learnhouse
```
#### Go to the directory
```shell copy
cd learnhouse
```
### Build and run LearnHouse
```shell copy
docker-compose up -d
```
### Access LearnHouse
When running the application for the first time, an admin account and organization is created for you, look for the admin credentials in the logs.
#### Login to your account
Open your browser and go to [http://localhost/login](http://localhost/login) to access the application.
#### Change your password
After logging in, don't forget to [change your password](http://localhost/dash/user-account/settings/security)
<Callout type="warning" >
It is important to change the default password to a another one, reducing the risk of unauthorized access if your server is compromised.
</Callout>
### You're all set!
Thanks for using LearnHouse 🎉
</Steps>
## Further configuration
You should be ready to go when following the steps above but if you'd live to enable features like **AI**, **Emails**, **Multi-org**, or customize the application, check the [configuration guide](/self-hosting/configuration).
### Environment variables usage with the LearnHouse Docker image
You can mix frontend and backend env vars defined in the COnfiguration page, in a single file like the one included on the repository (extra/example-learnhouse-conf.env)
```env filename="extra/example-learnhouse-conf.env" copy
# Frontend
NEXT_PUBLIC_LEARNHOUSE_MULTI_ORG=false
NEXT_PUBLIC_LEARNHOUSE_DEFAULT_ORG=default
# Backend
LEARNHOUSE_COOKIE_DOMAIN=.localhost
LEARNHOUSE_SQL_CONNECTION_STRING=postgresql://learnhouse:learnhouse@db:5432/learnhouse
LEARNHOUSE_REDIS_CONNECTION_STRING=redis://redis:6379/learnhouse
```
```yaml filename="docker-compose.yml" {7-8} copy
app:
build: .
ports:
- "80:80"
volumes:
- .:/usr/learnhouse
env_file:
- ./extra/example-learnhouse-conf.env
depends_on:
db:
condition: service_healthy
redis:
condition: service_healthy
```
## Found bugs ?
If you find any bugs or have any suggestions, please open an issue on our [GitHub repository](https://github.com/learnhouse/learnhouse/issues/new/choose), we would love to hear from you.
Please include as much information as possible, like the steps to reproduce the bug, the expected behavior and the actual behavior.

31
pages/self-hosting/overview.mdx
View File

@@ -2,17 +2,30 @@
LearnHouse is open source software and can be installed and maintained on just about any Cloud provider. We also support different hosting schemas like using AWS S3 or CloudFlare R2 for content storage.
## LearnHouse Cloud vs Self Hosting
A common question we get from developers is whether they should use our official platform, or host the codebase on their own server independently. Deciding which option is best for you comes with some nuance, so below is a breakdown of the differences to help you decide what will fit your needs best.
| | LearnHouse Cloud | Self Hosting |
| ----------------------------- | ------------------------------------------------ | ----------------------------- |
| 🌍 Worldwide CDN | Included | Manual + Additional cost |
| 🔄 Weekly updates | ✅ | Manual |
| 🚧 Maintenance & Updates | ✅ | Manual |
| 🛡️ Security | ✅ | Manual |
| ⚠️ Threat & uptime management | ✅ | ❌ |
| 🔒 SSL Certificate | ✅ | Manual |
| 📦 Continuous Backups | ✅ | Manual + Additional cost |
| ⚡ Scalability | ✅ | Depends on the cloud provider |
| 👨‍💻 Direct SSH & DB access | ❌ | ✅ |
| 🚑 Product Support | Email | Community |
| 💟 Where your money goes | Supporting the team + New Features in LearnHouse | 3rd party companies |
## Prerequisites
- Node.js 18.x
- Python 3.11
- Pnpm
- Docker
- Docker Compose
- [Docker](https://docs.docker.com/get-docker/)
- A server with at least 2GB of RAM
## Steps
## Guides
- [Get started & Install LearnHouse](/setup-dev-environment)
- [Self hosting Guide](/self-hosting/hosting-guide)
- [Configure LearnHouse](/self-hosting/configuration)

104
pages/setup-dev-environment.mdx
View File

@@ -1,19 +1,22 @@
import { Callout } from "nextra-theme-docs";
import { Steps } from "nextra-theme-docs";
# Setting up a dev environment
# Setting up a Dev environment
This is a guide to set up a dev environment for LearnHouse, it will guide you through the installation of the backend and the frontend.
Some parts are subject to automation in the future, making the process easier.
## Prerequisites
- [Docker](https://docs.docker.com/get-docker/)
- [Node.js 21.x](https://nodejs.org/en/download/)
- [pnpm](https://pnpm.io/installation)
- [Python 3.12.x](https://www.python.org/downloads/)
- [Poetry](https://python-poetry.org/docs/)
- macOS, Linux or Windows
## Backend configuration
<Steps>
### Install Docker
To install Docker, follow the instructions for your operating system on the [Docker website](https://docs.docker.com/get-docker/).
### Get the repository
@@ -25,7 +28,7 @@ git clone https://github.com/learnhouse/learnhouse
cd learnhouse
```
### Build & run the Backend
### Build & install LearnHouse
This will build & run the backend and the database docker images
@@ -33,26 +36,46 @@ This will build & run the backend and the database docker images
docker-compose up -d
```
### Enable install mode
This will install all the dependencies needed for the backend
- A **Postgres** database
- A **Redis** server
- A **Collaboration** nodejs server
- _A built LearnHouse App\* (Frontend & Backend)_
<Callout type='info'>
You should **ignore** the Built LearnHouse App as it's not needed for the dev environment, in this case it will be useful only for installing learnhouse contents (Roles, Organization, Users in the database)
</Callout>
### Run the backend in dev mode
You'll need to modify the config file to enable the install mode
```env filename="./config/config.yaml" {6-7}
site_name: LearnHouse
site_description: LearnHouse is an open-source platform tailored for learning experiences.
contact_email: hi@learnhouse.app
#### Go to the backend folder
general:
development_mode: true
install_mode: true
```shell copy
cd apps/api
```
<Callout type="info" >
To learn more about Configuration options, please refer to the [Configuration](/self-hosting/configuration) documentation
</Callout>
<Callout type="warning" >
If using LearnHouse in production, please set the install mode and development mode to **false**
</Callout>
#### Install python dependencies
```shell copy
poetry install
```
#### Run the Backend in Dev mode
```shell copy
poetry run python app.py
```
<Callout type="info">To learn more about Configuration options, please refer to the [Configuration](/self-hosting/configuration) documentation</Callout>
#### Check the API
Go to [http://localhost:1338/docs/](http://localhost:1338/docs/)
</Steps>
## Frontend configuration
@@ -70,7 +93,7 @@ cd apps/web
This will install all the dependencies needed for the frontend
```shell copy
npm i
pnpm i
```
Add an .env file in the front folder with the following content
@@ -92,40 +115,37 @@ NEXT_PUBLIC_LEARNHOUSE_DOMAIN=localhost:3000
Run the dev environment
```shell copy
npm run dev
pnpm run dev
```
### Get to the install page
Go to [http://localhost:3000/install](http://localhost:3000/install)
<br />
<img style={{ borderRadius: 10 }} quality={100} src="/img/pages/dev-env/install.png" alt="Hello" width={800} height={500} />
</Steps>
## Install LearnHouse
<Steps>
### Go through the install process
Create your Organization, Account and roles.
### Configure your Organization as the default one
You'll need to update the front env file to set your Organization as the default one, use the **slug** of your organization.
Copy this content to the .env file in the web folder
```env filename="apps/web/.env" {2}
NEXT_PUBLIC_LEARNHOUSE_MULTI_ORG=false
NEXT_PUBLIC_LEARNHOUSE_DEFAULT_ORG=REPLACE_WITH_YOUR_ORG_SLUG
NEXT_PUBLIC_LEARNHOUSE_DEFAULT_ORG=default
NEXT_PUBLIC_LEARNHOUSE_API_URL=http://localhost:1338/api/v1/
NEXT_PUBLIC_LEARNHOUSE_BACKEND_URL=http://localhost:1338/
NEXT_PUBLIC_LEARNHOUSE_DOMAIN=localhost:3000
NEXT_PUBLIC_LEARNHOUSE_COLLABORATION_WS_URL=wss://localhost:1998
```
Make sure to change the `NEXT_PUBLIC_LEARNHOUSE_DEFAULT_ORG` to the organization you want to set as the default one, you''l find the organization slug in the database in the `organizations` table
Here it is set to `default` which is the default organization created by the backend when you ran the backend in the previous steps
### Congratulations, you're done! 🎉
Visit the app at [http://localhost:3000/](http://localhost:3000/)
</Steps>
## Next Steps
Thanks for contributing to LearnHouse 💟
You'll find here some issues/ features we need help with, feel free to contribute to any of them
- [Help Wanted Issues](https://github.com/learnhouse/learnhouse/labels/help%20wanted)