mirror of
https://github.com/cpvalente/ontime.git
synced 2026-07-26 10:38:55 +00:00
Cameron Slipp
122 lines
4.8 KiB
Markdown
122 lines
4.8 KiB
Markdown
# GETTING STARTED
|
|
|
|
Ontime consists of 3 distinct parts
|
|
|
|
- **client**: A React app for Ontime's UI and web clients
|
|
- **electron**: An electron app which facilitates the cross-platform distribution of Ontime
|
|
- **server**: A node application which handles the domains services and integrations
|
|
|
|
The steps below will assume you have locally installed the necessary dependencies.
|
|
Other dependencies will be installed as part of the setup
|
|
|
|
- **node** (~22)
|
|
- **pnpm** (~10)
|
|
- **docker** (only necessary to run and build docker images)
|
|
|
|
## LOCAL DEVELOPMENT
|
|
|
|
The electron app is only necessary to distribute an installable version of the app and is not required for local
|
|
development.
|
|
Locally, we would need to run both the React client and the node.js server in development mode
|
|
|
|
From the project root, run the following commands
|
|
|
|
- **Install the project dependencies** by running `pnpm i`
|
|
- **Create a local build** by running `pnpm build`, this will populate local dependencies
|
|
- **Run dev mode** by running `pnpm dev` or `pnpm dev:electron` to get the electron window
|
|
|
|
### Debugging backend
|
|
|
|
The previous command will start the development servers for both the client, server and electron applications.
|
|
Typically in dev mode we prefer to start these in separate terminals to help with error tracking and debugging.
|
|
|
|
We do that by creating two terminals an running
|
|
|
|
- **Run the React UI** by running `pnpm dev --filter=ontime-ui`
|
|
- **Run the nodejs server** by running `pnpm dev --filter=ontime-server`
|
|
|
|
- If you need to set breakpoints and inspect the code execution, enable Node.js inspect mode by running `pnpm dev:inspect --filter=ontime-server`.
|
|
|
|
## TESTING
|
|
|
|
Generally we have 2 types of tests.
|
|
|
|
- Unit tests for functions that contain business logic
|
|
- End-to-end tests for core features
|
|
|
|
### Unit tests
|
|
|
|
Unit tests are contained in mostly all the apps and packages (client, server and utils)
|
|
|
|
You can run unit tests by running `pnpm test:pipeline` from the project root.
|
|
This will run all tests and close test runner.
|
|
|
|
Alternatively you can navigate to an app or project and run `pnpm test` to run those tests in watch mode
|
|
|
|
### E2E tests
|
|
|
|
E2E tests are in a separate package. On running, [playwright](https://playwright.dev/) will spin up an instance of the
|
|
webserver to test against
|
|
These tests also run against a separate version of the DB (test-db)
|
|
|
|
Before running the E2E, you should first build the project with `pnpm build:local`.
|
|
|
|
You can run playwright tests from project root with `pnpm e2e`
|
|
|
|
When writing tests, it can be handy to run playwright in interactive mode with `pnpm e2e:i`. You would need to manually
|
|
start the webserver with `pnpm dev:server`
|
|
|
|
Some other useful commands
|
|
|
|
- `pnpm e2e:ui` open playwright UI
|
|
- `pnpm e2e --headed` run tests with a visible browser window
|
|
|
|
## CREATE AN INSTALLABLE FILE (Windows | MacOS | Linux)
|
|
|
|
Ontime uses Electron to distribute the application.
|
|
You can generate a distribution for your OS by running the following steps.
|
|
|
|
From the project root, run the following commands
|
|
|
|
- **Install the project dependencies** by running `pnpm i`
|
|
- **Build the UI and server** by running `pnpm build`
|
|
- **Create the package** by running `pnpm dist-win`, `pnpm dist-mac` or `pnpm dist-linux`
|
|
|
|
The build distribution assets will be at `.apps/electron/dist`
|
|
|
|
## DOCKER
|
|
|
|
Ontime provides a docker-compose file to aid with building and running docker images.
|
|
While it should allow for a generic setup, it might need to be modified to fit your infrastructure.
|
|
|
|
From the project root, run the following commands
|
|
|
|
- **Build docker image from** by running `docker build -t getontime/ontime .`
|
|
- **Run docker image from compose** by running `docker-compose up -d`
|
|
|
|
Other useful commands
|
|
|
|
- **List running processes** by running `docker ps`
|
|
- **Kill running process** by running `docker kill <process-id>`
|
|
|
|
## FORMATTING AND LINTING
|
|
|
|
Ontime uses [oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) for formatting and [oxlint](https://oxc.rs/docs/guide/usage/linter.html) for linting. Look for an [oxc extension](https://oxc.rs/docs/guide/usage/linter/editors) for your editor of choice.
|
|
|
|
- **Run formatter** by running `pnpm format`
|
|
- **Run linter** by running `pnpm lint`
|
|
|
|
## CONTRIBUTION GUIDELINES
|
|
|
|
If you want to propose changes to the codebase, please reach out before opening a Pull Request.
|
|
|
|
For new PRs, please follow the following checklist:
|
|
|
|
- [ ] You have updated and ran unit locally and they are passing. Unit tests are generally created for all utility functions and business logic
|
|
- [ ] You have ran code formatting and linting in all your changes
|
|
- [ ] The branch is clean and the commits are meaningfully separated and contain descriptive messages
|
|
- [ ] The PR body contains description and motivation for the changes
|
|
|
|
After this checklist is complete, you can request a review from one of the maintainers to get feedback and approval on the changes. \
|
|
We will review as soon as possible
|