From ca6b5702b808ec8d3abe1a267447c43c1b71d3bb Mon Sep 17 00:00:00 2001 From: David Battefeld Date: Fri, 12 Jul 2024 18:38:48 +0200 Subject: [PATCH] docs: update README closes #8 --- README.md | 81 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index a9c2060..097fefa 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,53 @@ # Skylarks-FE-Next -New experimental frontend for the [website of the Berlin Skylarks Baseball & Softball Club](https://www.tib-baseball.de/). +New experimental frontend for the [website of the Berlin Skylarks Baseball & Softball Club](https://www.tib-baseball.de/). Built with SvelteKit, Skeleton UI and Tailwind CSS. -Not actively used in production at the moment. +## Concept / Background -## Status quo -The website is served as a standard TYPO3 CMS website with PHP-based Fluid templates, enriched with some basic JavaScript. +As of now, different types of data are being processed in different backends: +* The main backend [Baseball & Softball Manager / BSM](https://bsm.baseball-softball.de/) of the German Baseball & Softball Federation (DBV). + * Everything related to organised play is processed there (clubs, games, leagues, teams, player, stats) + * Accessed via REST API (provided by BSM - _external_) +* The current Skylarks website, served as a [TYPO3 CMS](https://typo3.org/) website (PHP-based). + * Processes additional data that is distinct from BSM data: club teams, player profiles (with more data than what is available in BSM), + training times, game reports + * Mainly displayed in the TYPO3 frontend directly, but can also be accessed via REST API (custom - _internal_) -## Intended end result -The website is split into a modern frontend (this repository) and a headless backend focused solely on providing data. +## Project goal +This project is intended as a pure frontend that collects data from these sources and displays it in a user-friendly way. +Since usage is expected to be predominantly mobile, focus is on providing a Progressive Web App with mobile-first design. ---- +## Project requirements +* basic familiarity with the concepts of SvelteKit and Svelte - there is an excellent [official tutorial](https://learn.svelte.dev/tutorial/welcome-to-svelte) available +* Node.js `v20` or higher +* access to Berlin Skylarks environment secrets and API keys + +## Local Development -## SvelteKit generated documentation +1. Clone the repository ```bash -# create a new project in the current directory -npm create svelte@latest +git clone git@github.com:tib-baseball-softball/skylarks-fe-next.git +cd skylarks-fe-next +``` -# create a new project in my-app -npm create svelte@latest my-app +2. Set up environment + +```bash +cp .env.dist .env ``` +* BSM API key (from BSM user account with at the club admin scope for Berlin Skylarks) +* API Auth Header (from `.env` on TYPO3 host server) +* `PUBLIC_BACKEND_URL` can either be set to a TYPO3 dev environment running locally or the production URL -## Developing +3. Get project dependencies -Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server: +```bash +npm install` +# yarn/pnpm/bun could also work, untested +``` + +4. Start the dev server (watches for file changes automatically) ```bash npm run dev @@ -33,14 +56,30 @@ npm run dev npm run dev -- --open ``` -## Building +Default local port is http://localhost:5173/ -To create a production version of your app: +## Deployment + +Fully automated via GitHub Actions, deploys on every push to branch `main`, excluding documentation files and folders. + +### Server Setup / Manual Deployment + +What the GitHub Action does: +1. `npm ci && npm run build` for production build output +2. sets static environment variables +3. copies build output to server via `rsync` +4. App is served as Node.js application listening on a specific port +5. Process is managed by [PM2](https://pm2.keymetrics.io/) +6. The [Caddy Webserver](https://caddyserver.com/) is used as reverse proxy. -```bash -npm run build -``` -You can preview the production build with `npm run preview`. +## Bugs and Problems +* Please open an issue in this repository. -> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment. +## Terms of use +Licensed under [AGPL-3](LICENSE). + +--- + +> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=Readme) to give feedback on this template. +---