From bce327698b01aeb096c3b82de73b61b99ef2d5fb Mon Sep 17 00:00:00 2001 From: ivarlovlie Date: Fri, 11 Nov 2022 16:14:58 +0700 Subject: refactor/feat: Update documentation/clarify project --- README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 56 insertions(+), 16 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 8ed5fea..be9fe28 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,20 @@ -# Great Office +# Greatoffice -This codebase and all of its source code is licensed under the GNU General Public License v3.0, see [COPYING](COPYING) for more information. +> This codebase and all of its source code is licensed under the GNU General Public License v3.0, see [COPYING](COPYING) for more information. -## server +This repository contains all the code for greatoffice, a business management system. + +The platform aims to equip it's users with tools to do +- project management +- time tracking +- invoicing +- documenting +- ticketing +- task management + +See it live at https://dev.greatoffice.app + +## code/api Contains an ASP.NET Core Web API project using the [ApiEndpoints](https://github.com/ardalis/ApiEndpoints) paradigm. @@ -10,11 +22,36 @@ It handles all data operations (except administrative operations) for the platfo To run it you need .NET 6 and a PostgreSQL instance. -### Environment +### Database schemas + +The application schema is managed and described using entity framework core, to apply the latest migration use `dotnet ef database update` + +> This operation requires that you have the dotnet-ef tools installed, use `dotnet tool install -g dotnet-ef` to do so. +> +> In addition to that it requires you to have populated the required environment variables or enabled flight mode. + +Besides the application schema the api also needs a quartz database, sql scripts to create these in postgres is provided at `code/api/sql/quartz-*.sql`. + +I recommend using a seperate database for the quartz schema and app schema, since the app schema is managed by ef core and the quartz schema is not. +### Environment/Configuration -The server is configured through environments variables, in development [user-secret](https://docs.microsoft.com/en-us/aspnet/core/security/app-secrets) is a nifty tool. +The api uses Hashicorp's vault to manage it's configuration, environment variables is used to point the api in the direction of the vault json object that contains the configuration. -All environment variables the server needs to function properly is specified in [src/server/Data/Static/AppEnvironmentVariables.cs](./server/src/Data/Static/AppEnvironmentVariables.cs). +The configuration is described by [code/api/src/Data/Models/AppConfiguration.cs](./code/api/src/Data/Models/AppConfiguration.cs). + +I recommend using [user-secrets](https://docs.microsoft.com/en-us/aspnet/core/security/app-secrets) to set environment variables when developing. + +All environment variables the api needs to function properly is specified in [code/api/src/Data/Static/AppEnvironmentVariables.cs](./code/api/src/Data/Static/AppEnvironmentVariables.cs). + +#### Minimum required configuration + +The following configuration keys need valid values in order to start the api (regardless of environment): +- Starting with DB_ +- Starting with QUARTZ_DB_ +- Equal to APP_CERT + +#### Flight mode +If you need to skip the setup of vault or is unable to reach your vault instance, set isInFlightMode to true in [code/api/src/Services/VaultService.cs](./code/api/src/Services/VaultService.cs). ### Building and Developing @@ -22,21 +59,24 @@ To run the server in development mode use `dotnet run` (`dotnet watch` for hot-r To build the server locally use `dotnet build` or `dotnet build -c Release` for production builds. -## tests +A helper script is available at [`code/api/build_and_push.sh`](code/api/build_and_push.sh) that handles, +- Optionally commiting, taging and pushing latest changes to remote git source +- Building a docker image +- Pushing the docker image to the default registry at dr.ivar.systems +- Bumping version number -Contains integration tests for the web-app, written in .NET and xunit with Playwright for browser mocking. +## code/app -It automatically starts the server and expects the server to host the web-app at /index.html. +Contains an svelte kit application that acts as the frontend for greatoffice -Use `dotnet run` to run the tests. +### Environment -## apps/projects +The app reads environment variables from [`code/app/.env`](code/app/.env), keys need to start with `VITE_`. -The projects app is a svelte pwa that handles +### Building and Developing -- project management -- time tracking +To run the app in development mode use `pnpm run dev`. -## apps/web-shared +To build a production build use `pnpm run build`, the production build is placed in the `build` folder. -A source lib containing models, shared styles and shared components for all of great office's js clients/apps. +> Use `node build/index.js` (minimum v16) to run the app \ No newline at end of file -- cgit v1.3