Merge pull request #107 from vim/documentation/README

docu(README) => Add getting started section in readme

Author: hanEck

.env.example

@@ -4,4 +4,19 @@ DATABASE_CLIENT=mysql2
 DATABASE_USERNAME=vim
 DATABASE_PASSWORD=super-secret
 DATABASE_PORT=3306
-DATABASE_SSL=false
+DATABASE_SSL=false
+
+WEB_DATABASE_NAME=vim
+NEXT_PRIVATE_STANDALONE=true
+NEXTAUTH_SECRET=testsecret
+
+CMS_DATABASE_NAME=vim_cms
+CMS_HOST=0.0.0.0
+CMS_PORT=1337
+CMS_APP_KEYS=testkey1,testkey2
+CMS_API_TOKEN_SALT=testtoken
+CMS_ADMIN_JWT_SECRET=testsecret
+CMS_JWT_SECRET=testsecret
+CMS_TRANSFER_TOKEN_SALT=testtoken
+CMS_DISABLE_UPDATE_NOTIFICATION=false
+CMS_TELEMETRY_DISABLED=true

README.md

@@ -4,13 +4,43 @@
 This is the relaunch of the new www.vim.org website. We have found a small team that will take on the
 beautiful task of rebuilding the website with current design and new concepts.
 
-The new development should not take place behind closed doors, we want to 
+The new development should not take place behind closed doors, we want to
 make the new development public and transparent for you.
 
 Soon there will be a test system where you can follow the current status successively.
 
 Of course, we will involve you, the community, in the design by collecting ideas and feedback.
 
+# Build
+
+Prerequisites
+
+* docker & docker-compose
+* npm
+
+### Getting started
+
+Run the application locally with these make commands.
+
+```sh
+# start prebuilt containers
+make start
+
+# or start containers for local development
+make dev
+```
+
+This will setup default configuration (including dummy secrets),
+install npm dependencies and start the application using docker on port `3000`.
+
+### Build locally
+
+The following steps must be carried out:
+1. Copy contents of `.env.example` files on `root`, `root/cms` and `root/web` into `.env` file
+2. Install npm dependencies with `npm install` in the `root`, `root/cms` and `root/web` folder.
+3. Startup: `docker compose -f docker-compose.local.yml up`
+
+For more information about the headless CMS used in this project, visit the official documentation: https://docs.strapi.io/
 
 # Requirements
 
@@ -27,7 +57,7 @@ Add your requirements here:
 ## Non-Functional Requirements
 
 * We want to continue using MySQL 8 as the database system.
-* We want the website to be fundamentally secure and avoid typical web application vulnerabilities (like SQL injection, XSS, ...) by design. 
+* We want the website to be fundamentally secure and avoid typical web application vulnerabilities (like SQL injection, XSS, ...) by design.
 * The hashing of the user passwords is to be migrated to a hashing procedure that corresponds to the state of the art.
 * The frontend/backend stack shall:
   - should be maintainable and expandable in the future with reasonable effort

local-startup.sh

@@ -1,6 +1,7 @@
 .PHONY: clean build run logsmake
 
 DC=docker compose -f docker-compose.local.yml
+DC_DEV=docker compose -f docker-compose.dev.yml
 
 default: help
 init: init-env check-env install
@@ -16,14 +17,17 @@ help:
 	@echo "TARGETS:"
 	@echo "  init:                                initialize project"
 	@echo
+	@echo "  // For starting application"
+	@echo "  start:                                 use prebuilt containers"
+	@echo
 	@echo "  // For local development"
 	@echo "  dev:                                 start local development"
 	@echo "   dev-all:                            start all dev containers"
 	@echo "   dev-web:                            start dev web image"
 	@echo "   dev-cms:                            start dev cms image"
 	@echo "   dev-db:                             start dev db image"
 	@echo
-	@echo "  // For building containers"
+	@echo "  // For building local containers"
 	@echo "  build:                               build all"
 	@echo "   build-web:                          build web image"
 	@echo "   build-cms:                          build cms image"
@@ -56,14 +60,14 @@ install:
 
 init-env:
 	test -f .env || cp .env.example .env
-	test -f web/.env || cp .env.example web/.env
+	cd web/ && ( test -f .env || cp .env.example .env )
 	cd cms/ && ( test -f .env || cp .env.example .env )
 	@echo '-----------------------------------------------------'
-	@echo 'please update the .env files with the missing secrets'
+	@echo 'please update the default secrets in the .env files'
 
 check-env:
 	./scripts/check-env.sh .env.example .env
-	./scripts/check-env.sh .env.example web/.env
+	./scripts/check-env.sh web/.env.example web/.env
 	./scripts/check-env.sh cms/.env.example cms/.env
 
 logs:
@@ -73,6 +77,9 @@ clean:
 	$(DC) down
 	$(DC) down --volumes
 
+start:
+	$(DC_DEV) up -d
+
 stop:
 	$(DC) stop
 
@@ -85,6 +92,7 @@ stop-cms:
 stop-db:
 	$(DC) stop db
 
+
 ## DOCKER DEVELOPMENT
 dev: init dev-all