Doughnut

About

Doughnut is a Personal Knowledge Management (PKM) tool combining zettelkasten style of knowledge capture with some features to enhance learning (spaced-repetition, smart reminders) and ability to share knowledge bits with other people (for buddy/team learning).

For more background info you can read::

Product Backlog

Story Map

Doughnut Technology Stack

Current Architecture Videos

Getting started

1. Quick Start - doughnut development environment setup

🏁 From the root of doughnut directory, in a terminal, run:

Please ensure your git configuration is appropriate for your OS to respect the correct line endings:

git config --global core.autocrlf input
git add --renormalize .

Install Nix package manager if you haven't already with

./setup-doughnut-dev.sh

Install direnv and activate direnv macOS: brew install direnv Ubuntu/Debian (includes WSL2 with Ubuntu): sudo apt-get install -y direnv Fedora: sudo dnf install direnv Change directory to your cloned doughnut folder path and run the below:

echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
direnv allow

Subsequently, each time your change directory into your doughnut cloned folder, nix flakes will be auto loaded. Each time you change directory away from doughnut directory, the nix environment will be auto unloaded.

Ensure your OS (WSL2/Ubuntu/Fedora, etc) has /bin/sh point to bash. If you are using Ubuntu where /bin/sh is symlinked to dash, please run sudo dpkg-reconfigure dash and answer "No" to reconfigure to bash as default.

🪟 WSL2 with WSLg:

Additional things to note for Microsoft Windows10/Windows11 developers using WSL2g with Ubuntu-23.04.

⚠️ DO NOT CLONE doughnut source to a MS Windows directory (e.g. `/mnt/c/`)!!! Instead, in your WSL2 session, `cd ~` then `git clone git@github.com:nerds-odd-e/doughnut.git`

⚠️ Nix and sdkman don't play very well together. A simple way around is to move or rename ~/.sdkman dir and comment out sdkman related config in ~/.<SHELL>rc.

🚦 🚧 ONLY if you hit problems with the above quick-start setup, you should manually walk through the local development environment nix setup.

2. Setup and run doughnut with migrations in 'E2E' profile (backend app started on port 9081)

From the root of your doughnut directory, start your doughnut nix development environment with

If you have direnv installed & configured right, just cd to the path where you cloned doughnut Github source code and the nix develop environment will autoload, OTHERWISE run:

nix develop

Start the backend service/application

pnpm sut

Rerun it each time you reset the database or change backend java code (java is still a compiled language).

2.1 Run full backend unit tests suite from terminal/CLI

From doughnut source root directory:

pnpm backend:verify

3. IntelliJ IDEA settings

4. End-to-End Test / Features / Cucumber / SbE / ATDD

We use cucumber Gherkin + cypress (test driver) Javascript/Typescript framework to drive the end-to-end test suite.

Cucumber

The Cypress+Cucumber tests are in JavaScript/TypeScript.

cypress

cypress-cucumber-preprocessor
We use mountebank to mock external backend services.
- To run mountebank in debug mode, run pnpm mb --loglevel debug.

Commands

For MS Windows WSL2 users:

you need to ensure your WSL2 Linux has xvfb installed manually before you can run cypress. This is not managed by Nix!
export NODE_OPTIONS="--max-old-space-size=4096" before running any cypress related commands ( e.g. cy:open or cy:run).

Purpose	Command (run from `doughnut` source root directory)
Install needed e2e tooling	`pnpm --frozen-lockfile recursive install`
Start SUT (backend system under test)	`pnpm sut` (starts backend SUT ONLY)
Start Mock for external backend	`pnpm start:mb` (starts mocked external backend ONLY)
Start ONLY the Cypress IDE	`pnpm cy:open` (starts Cypress IDE ONLY)
Run all e2e test	`pnpm verify` (compile frontend assets, start backend SUT, mountebank virtual service provider & cypress headless e2e testing)
Run cypress with Backend & Frontend	`pnpm test:open` (starts frontend SUT in HMR mode, backend SUT, mountebank virtual service provider & cypress IDE)
Generate TypeScript Interfaces	`pnpm generateTypeScript` (Generate TypeScript Interfaces from backend JSON classes. Should run manually every time backend service changes)

Structure

Purpose	Location
feature files	`e2e_test/features/*.feature`
step definitions	`e2e_test/step_definitions/*.ts`
custom DSL	`e2e_test/support/*.ts`
cucumber hooks	`e2e_test/step_definitions/common/hook.ts`
test fixtures	`e2e_test/fixtures/.`
cypress config	`e2e_test/config/*.json`
cypress plugins	`e2e_test/plugins/index.ts`

5. Database migrations

You can find the database migrations in backend/src/main/resources/db/migration/. The migrations are run automatically when the backend app starts up. It will also run the migrations for test when you run pnpm backend:test. To trigger the test DB migration manually, run backend/gradlew migrateTestDB. To connect to the local DB: mysql -S $MYSQL_HOME/mysql.sock -u doughnut -p (password=doughnut).

6. Vue3 web-app frontend

We chose Vue3 + Vite to build our frontend.

The TypeScript code calling the backend services is generated from the backend code. Run

pnpm generateTypeScript

To do the code generation. There are two steps in this command:

Generate openAPI docs from the backend service into ./open_api_docs.yaml.
Generate TypeScript interfaces from the openAPI docs, into frontend/src/generated.

If the step 1 is not done, a unit test will fail. If the step 2 is not done, CI will fail (./assert_generated_type_script_up_to_date.sh).

How-to

Run frontend unit tests (with Vitest)

From doughnut source root directory

pnpm frontend:verify

Run frontend web-app (app will launch on port 5173)

pnpm frontend:sut

Build & Bundle Vue3 frontend web-app assets and startup backend app (backend webapp will launch on port 9081).

pnpm frontend:build
pnpm sut

Expect to find minified and uglified web bundle assets in backend/src/main/resources/static directory:

❯ pwd
/home/lia/doughnut/backend/src/main/resources/static
❯ tree -L 3
.
├── assets
│   ├── main.32137c85.js
│   ├── main.b097c993.css
│   └── vendor.8f9eb49d.js
├── index.html
├── odd-e.ico
└── odd-e.png

1 directory, 6 files

7. Manual testing locally

When you have the backend and frontend running, you can manually test the application.

Visit http://localhost:5173/ to see the frontend web-app. The backend API is available at http://localhost:9081, and you will see the built frontend web-app there as well, but it wil not auto-reload on changes. So stay with the 5173 port.

Local test accounts:

User: 'old_learner', Password: 'password'
User: 'another_old_learner', Password: 'password'
User: 'admin', Password: 'password'

11. Architecture and Design documentation

Miro board

How to Contribute

We welcome product ideas and code contribution.
Collaborate over:
- GitHub Discussions for product ideas/features,
- GitHub Issues for reporting issues or bugs, OR
- doughnut gitter.im
FOSS style; Fork and submit GitHub PR.
- Please keep the PR small and on only one topic
- The code need to come with tests

Th3Un1q3/less-training-doughnut

Doughnut

About

Product Backlog

Doughnut Technology Stack

Current Architecture Videos

Getting started

1. Quick Start - doughnut development environment setup

Additional things to note for Microsoft Windows10/Windows11 developers using WSL2g with Ubuntu-23.04.

⚠️ DO NOT CLONE doughnut source to a MS Windows directory (e.g. `/mnt/c/`)!!! Instead, in your WSL2 session, `cd ~` then `git clone git@github.com:nerds-odd-e/doughnut.git`

2. Setup and run doughnut with migrations in 'E2E' profile (backend app started on port 9081)

2.1 Run full backend unit tests suite from terminal/CLI

3. IntelliJ IDEA settings

4. End-to-End Test / Features / Cucumber / SbE / ATDD

Commands

Structure

5. Database migrations

6. Vue3 web-app frontend

How-to

Run frontend unit tests (with Vitest)

Run frontend web-app (app will launch on port 5173)

Build & Bundle Vue3 frontend web-app assets and startup backend app (backend webapp will launch on port 9081).

7. Manual testing locally

8. Style Guide & Code linting/formating

9. Production environment

10. Doughnut source code secrets management

11. Architecture and Design documentation

How to Contribute

Th3Un1q3/less-training-doughnut

Doughnut

About

Product Backlog

Doughnut Technology Stack

Current Architecture Videos

Getting started

1. Quick Start - doughnut development environment setup

Additional things to note for Microsoft Windows10/Windows11 developers using WSL2g with Ubuntu-23.04.

⚠️ DO NOT CLONE doughnut source to a MS Windows directory (e.g. /mnt/c/)!!! Instead, in your WSL2 session, cd ~ then git clone git@github.com:nerds-odd-e/doughnut.git

2. Setup and run doughnut with migrations in 'E2E' profile (backend app started on port 9081)

2.1 Run full backend unit tests suite from terminal/CLI

3. IntelliJ IDEA settings

4. End-to-End Test / Features / Cucumber / SbE / ATDD

Commands

Structure

5. Database migrations

6. Vue3 web-app frontend

How-to

Run frontend unit tests (with Vitest)

Run frontend web-app (app will launch on port 5173)

Build & Bundle Vue3 frontend web-app assets and startup backend app (backend webapp will launch on port 9081).

7. Manual testing locally

8. Style Guide & Code linting/formating

9. Production environment

10. Doughnut source code secrets management

11. Architecture and Design documentation

How to Contribute

⚠️ DO NOT CLONE doughnut source to a MS Windows directory (e.g. `/mnt/c/`)!!! Instead, in your WSL2 session, `cd ~` then `git clone git@github.com:nerds-odd-e/doughnut.git`