What's that

This is a template to set up a backend ASP.NET Core project with React frontend. You could check it out at https://template.mcc-soft.de (credentials: admin/BSjo1M8jU760).

Developers are encouraged to start with setting up the environment and proceed to development how-to.

Template contains (you could also check CHANGELOG for latest changes):

1. ASP.NET Core backend (.NET 8)
   1. OpenIddict authentication (with support for Social Networks authentication)
   2. Guidance/example on how to structure backend
   3. Helpers for easy implementation of REST API for CRUD (with PATCH instead of UPDATE)
   4. Configured Domain events to apply DDD principles
   5. Localization (i18next), background jobs (Hangfire), etc.
   6. Audit logging for DB entities
   7. Logging via Serilog to:
      1. OpenSearch (credentials: backend-frontend-template/$a55IVHBhAJ@)
      2. Loggly (free up to 250MB/day). You could check out logs yourself (credentials: [email protected]/dBAeFm7_y5mq3)
2. React frontend
   1. Vite-based template
   2. API client autogeneration (including react-query hooks)
   3. UI Kit to simplify app restyling
   4. Guidance/examples on setting up forms (react-hook-form), tables (with sorting/paging) and filters
   5. Support for injecting environment variables (without rebuilding the app)
   6. Redux with persistence
   7. Routing with react-router
   8. Error-boundaries which works with suspense/react-query/code splitting
   9. Pre-built authentication UI
3. Build-script to build a single Docker container from backend and frontend
   1. package.json based build script (just run yarn build from repo root)
4. Azure-pipelines CI script which
   1. Builds Docker Image
   2. Uploads it to Container Registry (on Digital Ocean)
   3. Deploys Image to preconfigured agent
5. Instructions about configuring an agent to deploy aforementioned Docker Image on any linux PC (Digital Ocean prefered :))
6. Kubernetes deployment files and guidance regarding deploy to kubernetes (in progress)

Setting up new project from template

Before using the template for your brand-new app run yarn rename -n YourProjectName. Additionally you can use -c YourCompanyName to change solution's root namespace. Use CamelCase for your project name. The script does the following (you could check the script and do this manually if you like to):

1. Rename all files/folders from 'TemplateApp' to your project name.
2. Change all namespaces, classnames, database names, dockerfiles and deployment scripts to suit your project
3. Adjust SPA port number to something random, so that it doesn't clash with other projects (in package.json: 'start' script, PORT=3011; in main app .csproj: `http://localhost:3011/)

Create a new git repository and copy everything (except .git folder) to it. Don't forget to change the favicons/tiles in frontend/public folder to the logo of your project (use https://realfavicongenerator.net/ to create favicons in all required sizes)

How to run locally

1. Check that connection string in appsettings is correct. Default connection string assumes that you have Postgres running on localhost on standard port with user/pass: postgres/postgres. Adjust connection string if the assumption is wrong.
   1. Make sure the target database exists (or that the postgres user has rights to create databases).
2. Run backend (Open webapi/MccSoft.TemplateApp.sln in Rider/Visual Studio and hit F5)
3. Run frontend (yarn start from frontend folder)
4. Frontend will open up in browser. Use that url to test the app!
5. (To authorize, you could use a preconfigured user. Login/Password is in appsettings.json under DefaultUser section)

How to set up CI/CD

1. First of all, you need to create an email for your project. It will be needed for registering in 3rd party systems that the project will use (e.g. Sentry and Loggly)
2. Go to Azure and create Pipeline. Specify .ci/azure-pipelines.yml as the source of pipeline.
3. Set up Container Registry to push images to.
   1. You could use GitLab Container Registry (since it's private and free)
      1. Register a user in GitLab (using project email)
      2. Create a personal access token with read/write access to container registry at https://gitlab.com/-/profile/personal_access_tokens
      3. Add secret variable DOCKER_TOKEN to a pipeline (with value generated on previous step)
      4. Adjust DOCKER_REGISTRY (e.g. registry.gitlab.com/mcctemplateapp1/main) and DOCKER_USER (e.g. [email protected]) variables in pipeline.
4. (optional) If you want to add git Tags to your sourcecode when deploying to DEV/PROD, you need to do the following:
   1. Give access for WRITING to Repo for your Pipeline. Instructions: https://elanderson.net/2020/04/azure-devops-pipelines-manual-tagging/
   2. Set TAG_SOURCES_DEV and TAG_SOURCES_PROD variables in base.partial.yml.
5. Run your pipeline. The first Stage (build) should pass.
6. Disable Pipeline notifications in Azure (i.e. 'Run stage waiting for approval' and 'Manual validation Pending') https://dev.azure.com/mccsoft/TemplateApp/_settings/notifications. Also disable them in your personal profile: https://dev.azure.com/mccsoft/_usersSettings/notifications
7. Pipeline contains 2 stages for deploying to DEV and PROD. You could add new deployment stages by copying existing once.

Deploy

Here are the possible ways to deploy your app:

1. Kubernetes (k3s) on VM. It is the preferred and simplest deployment setup. Read the details in the instructions.
   • For low workloads you could host App & Postgres together on 1CPU/2GB VPS together (~5$ on Hetzner/MVPS)
2. Azure Web App. It's simple, use it if you already use Azure and are ok with paying quite a bit more than for a regular VM (5x more :))
3. [Obsolete] Docker-compose on VM. This is an obsolete way, instructions are available for backwards compatibility. It's NOT recommended for new projects, and even old ones should better switch to Kubernetes (k3s) :).