Windy/komga
1
0
Fork 0
mirror of https://github.com/gotson/komga.git synced 2025-01-07 03:07:16 +08:00
Code Issues Packages Projects Releases Wiki Activity
master
komga/DEVELOPING.md

76 lines
3.3 KiB
Markdown
Raw Permalink Normal View History

docs: add development guidelines
2020-02-25 14:57:07 +08:00
# Development guidelines
Thanks a lot for contributing to Komga!
docs: add requirements to DEVELOPING.md
2020-06-19 17:35:03 +08:00
## Requirements
You will need:
build: move JDK configuration for desktop app to Conveyor configuration
2024-12-13 10:38:04 +08:00
- Java JDK version 17+
ci(webui): use node 18
2023-11-27 14:47:26 +08:00
- Nodejs version 18+ (check the `.nvmrc` file)
docs: update DEVELOPING.md
2022-01-28 12:01:02 +08:00
## Setting up the project
docs: typo in DEVELOPING.md (#790) Missed tick
2022-02-02 10:28:38 +08:00
- run `npm install` in the `komga-webui` folder of the project. This will install the necessary tooling for the webui.
docs: add requirements to DEVELOPING.md
2020-06-19 17:35:03 +08:00
docs: add development guidelines
2020-02-25 14:57:07 +08:00
## Commit messages
Komga's commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) standard. This enables automatic versioning, releases, and release notes generation.
## Project organization
docs: update DEVELOPING.md
2023-09-24 18:01:12 +08:00
Komga is composed of 3 projects:
docs: add development guidelines
2020-02-25 14:57:07 +08:00
- `komga`: a Spring Boot backend server that hosts the APIs, but also serves the static assets of the frontend.
- `komga-webui`: a VueJS frontend, built at compile time and served by the backend at runtime.
docs: update DEVELOPING.md
2023-09-24 18:01:12 +08:00
- `komga-tray`: a thin desktop wrapper that displays a tray-icon
docs: add development guidelines
2020-02-25 14:57:07 +08:00
## Backend development
### Spring profiles
Komga uses Spring Profiles extensively:
docs: clarify CORS usage for frontend dev
2021-12-03 09:12:42 +08:00
- `dev`: add more logging, disable periodic scanning, in-memory database, and enable CORS from `localhost:8081` (the frontend dev server)
feat: change database from H2 to SQLite This is a major change, but done transparently. At startup, a migration from H2 to SQLite will be triggered: - if the H2 database is a file (not in memory) - if the H2 database has not been migrated yet - if the SQLite database is newly minted All the data will be transferred from H2 to SQLite before the startup of the application (before the API can serve any requests). After the migration, an empty file will be stored next to the H2 database file (same name with ".imported" suffix). The H2 database files will be automatically removed in a later version. A new configuration key is available to customize the file path of the SQLite database: `komga.database.file` The database backup feature has been removed. It might be re-added later on using a different logic. The IDs of entities have been changed from number to string in the API. closes #218
2020-07-16 07:54:53 +08:00
- `localdb`: a dev profile that stores the database in `./localdb`.
feat(api): claim status remove the claim profile added noclaim profile that will create initial user accounts if none exist related to #207
2020-07-05 11:59:20 +08:00
- `noclaim`: will create initial users at startup if none exist and output users and passwords in the standard output
- if `dev` is active, will create `admin@example.org` with password `admin`, and `user@example.org` with password `user`
feat: change database from H2 to SQLite This is a major change, but done transparently. At startup, a migration from H2 to SQLite will be triggered: - if the H2 database is a file (not in memory) - if the H2 database has not been migrated yet - if the SQLite database is newly minted All the data will be transferred from H2 to SQLite before the startup of the application (before the API can serve any requests). After the migration, an empty file will be stored next to the H2 database file (same name with ".imported" suffix). The H2 database files will be automatically removed in a later version. A new configuration key is available to customize the file path of the SQLite database: `komga.database.file` The database backup feature has been removed. It might be re-added later on using a different logic. The IDs of entities have been changed from number to string in the API. closes #218
2020-07-16 07:54:53 +08:00
- if `dev` is not active, will create `admin@example.org` with a random password that will be shown in the logs
docs: add development guidelines
2020-02-25 14:57:07 +08:00
### Gradle tasks
The backend project uses `gradle` to run all the necessary tasks. If your IDE does not have `gradle` integration, you can run the tasks from the root directory using `./gradlew <taskName>`.
Here is a list of useful tasks:
- `bootRun`: run the application locally, useful for testing your changes.
build(webui): upgrade vue cli to v5
2023-09-13 15:14:28 +08:00
- `prepareThymeLeaf`: build the frontend, and copy the bundle to `/resources/public`. You need to run this manually if
you want to test the latest frontend build hosted by Spring.
docs: add development guidelines
2020-02-25 14:57:07 +08:00
- `test`: run automated tests. Always run this before committing.
docs: add requirements to DEVELOPING.md
2020-06-19 17:35:03 +08:00
- `jooq-codegen-primary`: generates the jOOQ DSL.
docs: add development guidelines
2020-02-25 14:57:07 +08:00
`bootRun` needs to be run with a profile or list of profiles, usually:
feat(api): claim status remove the claim profile added noclaim profile that will create initial user accounts if none exist related to #207
2020-07-05 11:59:20 +08:00
- `dev,noclaim`: when testing with a blank database
- `dev,localdb,noclaim`: when testing with an existing database
docs: add development guidelines
2020-02-25 14:57:07 +08:00
There are few ways you can run the task with a profile:
- `./gradlew bootRun --args='--spring.profiles.active=dev'`
- On Linux: `SPRING_PROFILES_ACTIVE=dev ./gradlew bootRun`
- On Windows:
```
SET SPRING_PROFILES_ACTIVE=dev
./gradlew bootRun
```
- If you use IntelliJ, some Run Configurations are saved in the repository and available from the Gradle panel
## Frontend development
docs: update development documentation for port change
2023-05-24 11:25:52 +08:00
You can run a live development server with `npm run serve` from `/komga-webui`. The dev server will override the URL to connect to `localhost:25600`, so you can also run `gradle bootRun` to have a backend running, serving the API requests. The frontend will be loaded from `localhost:8081`.
docs: add development guidelines
2020-02-25 14:57:07 +08:00
docs: clarify CORS usage for frontend dev
2021-12-03 09:12:42 +08:00
Make sure you start the backend with the `dev` profile, else the frontend requests will be denied because of CORS.
docs: update DEVELOPING.md
2022-01-28 12:01:02 +08:00
## Docker
To build the Docker image, you need to:
build(webui): upgrade vue cli to v5
2023-09-13 15:14:28 +08:00
- have the webui built and copied to `/resources/public`. To do so, run `./gradlew prepareThymeLeaf`
docs: clarify docker steps
2023-03-03 20:51:51 +08:00
- prepare the docker image via JReleaser. To do so, run `./gradlew jreleaserPackage`
- the `Dockerfile` will be available in `komga/build/jreleaser/package/docker/`
Reference in New Issue Copy Permalink