Guide to Running the Plan ₿ Academy Platform Locally

Mar 18, 2025

In Summary

This tutorial provides step-by-step instructions for setting up the Bitcoin Learning Management System from Plan ₿ Academy on your local machine using Docker, dummy keys, and custom repository configurations.

If you didn’t understand the part above, don’t worry—this tutorial is for you!

How to Run Bitcoin Learning Management System Locally

This tutorial provides detailed steps to set up the platform, handle dummy keys, and customize repositories. Follow the steps below to avoid common issues and properly configure your local environment.

1. Prerequisites

Linux machine with Docker and Docker Compose installed (it has been reported working on Windows too).
sufficient nodejs version (tested: 22.12.0)
pnpm installed on your system.
Git configured for cloning repositories.

2. Clone the Repository
Clone the repository to your local machine:

git clone https://github.com/PlanB-Network/bitcoin-learning-management-system
cd bitcoin-learning-management-system

git clone https://github.com/PlanB-Network/bitcoin-learning-management-system
cd bitcoin-learning-management-system

3. Set Up Environment Variables

1. Duplicate the .env.example file:

cp .env.example .env

Edit the .env file, deleting the .example part of the name, now you have to include dummy keys for required variables. Example:

⚠️ This is a mandatory step, skipping it will result in errors such connection refusal between some of the containers.

Don't forget to add your dedicated Github PAT too in the file
```
# Dummy Keys for External Services
   SBP_API_KEY=dummyApiKey
   SBP_HMAC_SECRET=dummyHmacSecret
   STRIPE_SECRET=sk_test_dummySecretKey12345
   STRIPE_ENDPOINT_SECRET=dummyEndpointSecret12345
   SENDGRID_KEY=dummySendgridKey
```

4. Install Dependencies

Be sure to have installed a suitable nodejs version. As of 2024-12, v22.12.0 (LTS) has been proven working.

⚠️ Ubuntu 22.04 repository nodejs version is 12.22.9: too old to allow you install pnpm

To install nodejs, find instructions here; for example you may choose to use nvm installation method.

Before starting pnpm installing phase of necessary packages, be sure to have all dependencies installed, you can achieve this by running the following command:

sudo apt install libcairo2-dev libjpeg-dev libpango1.0-dev libgif-dev build-essential g++ libpixman-1-dev

Inside your ../bitcoin-learning-management-system/ folder, run the following command to install pnpm

pnpm install

__TIP:__Remember to update from time to time both dependencies and pnpm itself

5. Run the Containers
Inside your ../bitcoin-learning-management-system/ folder, start the development environment with Docker:

docker compose up --build -V

You also run this next command this way, you won't see the logs in your terminal.

docker compose up -d --build -V

This will build and start all the necessary containers from dockers.

6. Access the Application
Once the containers are running, access the frontend at:
[http://localhost:8181](http://localhost:8181)

Note: that the app will automatically reload if you change any source files.

7. Set up your database schema

On the first run, you will need to run the DB migrations.

To do so, run the migration script: pnpm run dev:db:migrate

pnpm run dev:db:migrate

8. Import Data from the Repository
To import data into the database, make a request to the API:

curl -X POST http://localhost:3000/api/github/sync

9. Fix Sync Volume Access Issues
If you encounter access issues with the cdn and sync volumes, run:

docker exec --user=root bitcoin-learning-management-system-api-1 chmod 777 /tmp/{sync,cdn}

then again:

curl -X POST http://localhost:3000/api/github/sync

10. Customize the Repository (Optional)
If you need to use a fork or a specific branch:

Edit the .env file to update the following variables:

DATA_REPOSITORY_URL=https://github.com/<your-username>/bitcoin-educational-content.git
   DATA_REPOSITORY_BRANCH=<your-branch>
   PRIVATE_DATA_REPOSITORY_URL=https://github.com/<your-username>/planB-premium-content.git
   PRIVATE_DATA_REPOSITORY_BRANCH=<your-branch>

2. Restart Docker:

docker compose down -v
docker compose up --build -V

3. Re-sync the repository data:

curl -X POST http://localhost:3000/api/github/sync

This tutorial ensures the platform is correctly set up with dummy keys, dependencies installed, and repositories customized as needed. 🎉 Good luck with your setup!

Commands for extra help

stop all containers

docker compose down

prune all existing containers and volumes

docker container prune -f
docker volume prune --all

recreate the containers with the same command used in the official guide and launch the sync script:

docker-compose up --build -V 
curl -X POST http://localhost:3000/api/github/sync

Did this work well for you?

Author

This tutorial has been written by Jonathan Ramos

You can say thanks by tipping the professor.

Jonathan Ramos

1Tutorials

Jonathan is a developer from Plan ₿ Network and graduated from Cubo +, hater of shitcoins and lover of Bitcoin technology as well as self sovereignty

developmentadoptionself-sovereignty

Credits

This tutorial has been proofread by jramos0

1/3Proofreading status

Even if this content is in its original language, human review is necessary to ensure its accuracy.

jramos0514 sats257 sats

*Rewards may vary based on the $ exchange rate

Every content on the platform is the result of a collaborative effort: each lesson, translation, and revision is made possible by the work of contributors. For this reason, we are always looking for proofreaders who can review our content in many languages. If you want to participate in the proofreading process, please reach out in our Telegram group and read our tutorial. We remind you that this content is open-source - licensed under CC BY-SA - so it can be freely shared and used, as long as the original source is credited.