From 8d7f016cfa0c1c7038378e6233b0e1b42084bdf1 Mon Sep 17 00:00:00 2001 From: swve Date: Mon, 3 Nov 2025 20:30:13 +0100 Subject: [PATCH] feat: new self hosting guide --- .github/images/readme/communityedition.png | Bin 0 -> 8701 bytes pages/self-hosting/hosting-guide.mdx | 154 ++++++++------------- pages/self-hosting/overview.mdx | 28 +++- 3 files changed, 82 insertions(+), 100 deletions(-) create mode 100644 .github/images/readme/communityedition.png diff --git a/.github/images/readme/communityedition.png b/.github/images/readme/communityedition.png new file mode 100644 index 0000000000000000000000000000000000000000..9c7ac71dc29fe0831cc7fcea8f8d767eaca8a361 GIT binary patch literal 8701 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 -Interested in helping test on Windows? Join our [Discord](https://discord.com/invite/CMyZjjYZ6x) community. + +**For complete installation instructions, please visit the [LearnHouse Community Edition repository](https://github.com/learnhouse/community-edition)**. This repository contains the latest Docker Compose setup, detailed configuration guides, and troubleshooting information. +## Quick Start + +**TLDR**: Clone the repository, copy `.env.example` to `.env`, configure your admin credentials, and run `docker-compose -f docker-compose.yml up -d`. Should be ready in less than 2 minutes! + +```bash +git clone https://github.com/learnhouse/community-edition.git +cd community-edition +cp .env.example .env +# Edit .env with your configuration +docker-compose -f docker-compose.yml up -d +``` + ## Prerequisites -- [Docker](https://docs.docker.com/get-docker/) -- At least 4 GB of RAM allocated to the container runtime +- **Docker Engine 20.10+** and **Docker Compose 2.0+** +- At least **2GB RAM** +- **10GB+ disk space** +- A domain name (optional, for production; use `localhost` for local development) -## Step by step +## Key Features - - -### Install Docker - -To install Docker, follow the instructions for your operating system on the [Docker website](https://docs.docker.com/get-docker/). +The Community Edition includes: -### Download the LearnHouse repository +- **Multi-container architecture** with PostgreSQL, Redis, and nginx +- **Environment-based configuration** via `.env` file +- **Initial admin setup** with configurable credentials +- **Production-ready** deployment options +- **Data persistence** with Docker volumes +- **Health checks** for all services +- **Comprehensive monitoring** and logging -```bash copy -git clone https://github.com/learnhouse/learnhouse -``` - -#### Go to the directory +## Important Configuration -```shell copy -cd learnhouse -``` +Before first start, make sure to set: -### Configure NextAuth +- `LEARNHOUSE_INITIAL_ADMIN_EMAIL`: Email for the first admin user +- `LEARNHOUSE_INITIAL_ADMIN_PASSWORD`: Password for the first admin user +- `NEXTAUTH_SECRET`: Generate with `openssl rand -base64 32` +- `LEARNHOUSE_AUTH_JWT_SECRET_KEY`: Generate with `openssl rand -base64 32` -Add these lines to your `.env` file. A template is available under `/extra/example-learnhouse-conf.env`. - - -To safely encrypt tokens and email hashes, you need a NextAuth secret. - -To create one, either run `npx auth secret`, or on UNIX based systems (MacOS/Linux) you can use `openssl rand -base64 33`. - -Copy this string into your .env file as NEXTAUTH_SECRET= + +**⚠️ Important**: Change the admin password after first login! The default credentials are only for initial setup. -```env filename=".env" copy -# NextAuth Configuration -NEXTAUTH_SECRET={generated_secret} -NEXTAUTH_URL=http://localhost:3000/ -``` +## Architecture -### Build and run LearnHouse +LearnHouse Community Edition uses a multi-container architecture: -```shell copy -docker-compose up -d -``` +- **learnhouse-app**: Combined Next.js frontend and FastAPI backend (includes internal nginx on port 80) +- **nginx**: Reverse proxy (port 80 externally) +- **db**: PostgreSQL database +- **redis**: Redis cache -### Access LearnHouse +All containers communicate via a Docker network. -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. +## Access LearnHouse -#### Login to your account +After starting, access LearnHouse at: +- **Frontend**: http://localhost -Open your browser and go to [http://localhost/login?orgslug=default](http://localhost/login?orgslug=default) to access the application. +Login with the initial admin credentials you configured in `.env`. -#### Change your password +## Further Configuration -After logging in, don't forget to [change your password](http://localhost/dash/user-account/settings/security) +For detailed information on: +- Environment variables +- Production deployment +- Data persistence and backups +- Monitoring and troubleshooting +- Advanced configuration options - - It is important to change the default password to a another one, reducing the risk of unauthorized access if your server is compromised. - +Please visit the **[LearnHouse Community Edition repository](https://github.com/learnhouse/community-edition)**. -### You're all set! +You can also check our [configuration guide](/self-hosting/configuration) for additional LearnHouse-specific settings like AI features, email configuration, S3 storage, and more. -Thanks for using LearnHouse 🎉 +## Found bugs? - -## 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. +If you find any bugs or have suggestions, please open an issue on the [Community Edition repository](https://github.com/learnhouse/community-edition/issues), 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. diff --git a/pages/self-hosting/overview.mdx b/pages/self-hosting/overview.mdx index e13e90b..ea21b08 100644 --- a/pages/self-hosting/overview.mdx +++ b/pages/self-hosting/overview.mdx @@ -2,6 +2,29 @@ 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. +### Quick Start + +**TLDR**: `cp .env.example .env` and run `docker-compose -f docker-compose.yml up -d` and inspect the logs, should be ready to go in less than 2 mins + +### Prerequisites + +- Docker Engine 20.10+ and Docker Compose 2.0+ +- At least 2GB RAM +- 10GB+ disk space +- A domain name (optional, for production; use `localhost` for local development) + +### Get Started + +For detailed installation instructions, configuration options, and troubleshooting guides, please visit the **[LearnHouse Community Edition repository](https://github.com/learnhouse/community-edition)**. + +The Community Edition includes: +- Complete Docker Compose setup +- PostgreSQL database +- Redis cache +- Built-in reverse proxy (nginx) +- Environment-based configuration +- Production-ready deployment guide + ## 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. @@ -20,11 +43,6 @@ A common question we get from developers is whether they should use our official | 🚑 Product Support | Email | Community | | 💟 Where your money goes | Supporting the team + New Features in LearnHouse | 3rd party companies | -## Prerequisites - -- [Docker](https://docs.docker.com/get-docker/) -- A server with at least 2GB of RAM - ## Guides - [Self hosting Guide](/self-hosting/hosting-guide)