Merge pull request #122 from Tietokilta/feat/installation-docs

Better installation instructions and customization experience

.env.example

@@ -9,9 +9,11 @@ PORT=3000
 # Choose mysql or postgres
 DB_DIALECT=<mysql|postgres>
 DB_HOST=localhost
-DB_USER=ilmomasiina
-DB_PASSWORD=secret
+#DB_PORT=<3306|5432>
+DB_USER=ilmo_user
+DB_PASSWORD=password
 DB_DATABASE=ilmomasiina
+#DB_SSL=false
 
 
 # Privacy-related settings
@@ -59,70 +61,74 @@ MAIL_FROM=<[email protected]>
 # a version supporting language detection.
 MAIL_DEFAULT_LANG=fi
 
+# If you want to send emails, choose either SMTP or Mailgun.
+# In development, you can omit both and emails will be printed to the console.
+
 # SMTP server host and credentials, if using direct SMTP.
-SMTP_HOST=''
+SMTP_HOST=
 SMTP_PORT=587
-SMTP_USER=''
-SMTP_PASSWORD=''
+SMTP_USER=
+SMTP_PASSWORD=
+SMTP_TLS=false
 
 # Mailgun API key and domain, if using it.
-MAILGUN_API_KEY=''
-MAILGUN_DOMAIN=''
+MAILGUN_API_KEY=
+MAILGUN_DOMAIN=
 # Mailgun server to use (defaults to api.eu.mailgun.net)
-MAILGUN_HOST='api.eu.mailgun.net'
+MAILGUN_HOST=api.eu.mailgun.net
 
 
 # URL settings
 
 # Canonical base URL for the app. Used by the backend.
 # Include $PATH_PREFIX, but NOT a final "/".
 # e.g. "http://example.com" or "http://example.com/ilmo"
-BASE_URL='http://localhost:3000'
+BASE_URL=http://localhost:3000
 
 # URI prefix for the app. Used for frontend URLs.
 # Include initial "/", but NOT a final "/".
 # e.g. "" or "/ilmo"
-PATH_PREFIX=''
+PATH_PREFIX=
 
 # URI prefix or full base URL to the API. Used by the frontend.
 # Leave empty to use "$PATH_PREFIX/api".
 # YOU SHOULD LEAVE THIS EMPTY unless you're building the frontend against a remote API.
 # Include "/api" if applicable but NOT a final "/".
-API_URL=''
+API_URL=
 
 # URL template for an event details page. Used by the backend for iCalendar exports.
 # Leave empty to use the default routes used by the frontend, i.e. "$BASE_URL/events/{id}".
 # YOU SHOULD LEAVE THIS EMPTY unless you're using a customized frontend with different paths.
 # Use the token {slug}, e.g. http://example.com/event/{slug}
-#EVENT_DETAILS_URL=''
+#EVENT_DETAILS_URL=
 
 # URL template for a signup edit page. Used by the backend for emails.
 # Leave empty to use the default routes used by the frontend, i.e. "$BASE_URL/signup/{id}/{editToken}".
 # YOU SHOULD LEAVE THIS UNSET unless you're using a customized frontend with different paths.
 # Use the tokens {id} and {editToken}, e.g. http://example.com/signup/{id}/{editToken}
 
-#EDIT_SIGNUP_URL=''
+#EDIT_SIGNUP_URL=
 
 # Allowed origins for cross-site requests to API. Separate with commas or use * for all.
-ALLOW_ORIGIN=''
+ALLOW_ORIGIN=
 
 
 # Sentry.io public DSN for error tracking (only used in production, leave empty to disable)
-SENTRY_DSN=''
+SENTRY_DSN=
 
 
 # Branding settings
 
 # Website strings (requires website rebuild)
-BRANDING_HEADER_TITLE_TEXT='Ilmomasiina'
-BRANDING_FOOTER_GDPR_TEXT='Tietosuoja'
-BRANDING_FOOTER_GDPR_LINK='http://example.com/privacy'
-BRANDING_FOOTER_HOME_TEXT='Example.com'
-BRANDING_FOOTER_HOME_LINK='http://example.com'
+BRANDING_HEADER_TITLE_TEXT=Ilmomasiina
+BRANDING_FOOTER_GDPR_TEXT=Tietosuoja
+BRANDING_FOOTER_GDPR_LINK=http://example.com/privacy
+BRANDING_FOOTER_HOME_TEXT=Example.com
+BRANDING_FOOTER_HOME_LINK=http://example.com
 
 # Email strings
-BRANDING_MAIL_FOOTER_TEXT='Rakkaudella, Tietskarijengi & Athene'
-BRANDING_MAIL_FOOTER_LINK='https://ilmo.athene.fi'
+BRANDING_MAIL_FOOTER_TEXT=Rakkaudella, Tietskarijengi & Athene
+BRANDING_MAIL_FOOTER_LINK=https://ilmo.athene.fi
 
 # iCalendar exported calendar name
-BRANDING_ICAL_CALENDAR_NAME='Ilmomasiina'
+BRANDING_ICAL_CALENDAR_NAME=Ilmomasiina

.eslintrc.js

@@ -15,7 +15,9 @@ module.exports = {
     "**/node_modules/**",
     "**/dist/**",
     "**/build/**",
-    ".eslintrc.js"
+    ".eslintrc.js",
+    "*.scss",
+    "*.json"
   ],
   "settings": {
     "react": {

.github/workflows/docker-build.yml

@@ -1,5 +1,19 @@
 name: Publish Docker image
 
+env:
+  # Change this to your repo name to build automatically on your fork.
+  expected_repo: 'Tietokilta/ilmomasiina'
+
+  # Change this to upload the built image to your own organization.
+  docker_tag: 'ghcr.io/tietokilta/ilmomasiina'
+
+  # Change these to customize your build.
+  branding_header_title_text: 'Tietokillan ilmomasiina'
+  branding_footer_gdpr_text: 'Tietosuoja'
+  branding_footer_gdpr_link: 'https://tietokilta.fi/kilta/hallinto/viralliset-asiat/rekisteriselosteet/'
+  branding_footer_home_text: 'Tietokilta.fi'
+  branding_footer_home_link: 'https://tietokilta.fi'
+
 on:
   push:
     branches:
@@ -15,6 +29,7 @@ jobs:
     permissions:
       packages: write
       contents: read
+    if: github.repository == env.expected_repo
     steps:
       -
         name: Check out the repo
@@ -34,7 +49,7 @@ jobs:
         id: meta
         uses: docker/metadata-action@v4
         with:
-          images: ghcr.io/tietokilta/ilmomasiina
+          images: ${{ env.docker_tag }}
           flavor: |
             latest=${{ github.ref == 'refs/heads/prod' }}
           tags: |
@@ -50,69 +65,19 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          # Customize your build here
           build-args: |
-            BRANDING_HEADER_TITLE_TEXT=Tietokillan ilmomasiina
-            BRANDING_FOOTER_GDPR_TEXT=Tietosuoja
-            BRANDING_FOOTER_GDPR_LINK=https://tietokilta.fi/kilta/hallinto/viralliset-asiat/rekisteriselosteet/
-            BRANDING_FOOTER_HOME_TEXT=Tietokilta.fi
-            BRANDING_FOOTER_HOME_LINK=https://tietokilta.fi
-
-  npm:
-    name: Publish JS packages
-    if: github.ref_type == 'tag'
-    runs-on: ubuntu-latest
-    permissions:
-      packages: write
-      contents: read
-    steps:
-      -
-        name: Check out the repo
-        uses: actions/checkout@v3
-      -
-        uses: pnpm/action-setup@v2
-        with:
-          version: 7
-      -
-        name: Setup Node.js for NPM
-        uses: actions/setup-node@v3
-        with:
-          registry-url: 'https://registry.npmjs.org'
-          node-version: '16'
-          cache: 'pnpm'
-      -
-        name: Install dependencies
-        run: |
-          npm install -g pnpm@7
-          pnpm install --frozen-lockfile --ignore-scripts
-      -
-        name: Build packages
-        run: |
-          pnpm run --filter @tietokilta/ilmomasiina-models build
-          pnpm run --filter @tietokilta/ilmomasiina-components build
-      -
-        name: Publish to NPM
-        run: |
-          pnpm publish --filter @tietokilta/ilmomasiina-models --no-git-checks --access public
-          pnpm publish --filter @tietokilta/ilmomasiina-components --no-git-checks --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      -
-        name: Setup Node.js for GitHub Packages
-        uses: actions/setup-node@v3
-        with:
-          registry-url: 'https://npm.pkg.github.com'
-      -
-        name: Publish to GitHub Packages
-        run: |
-          pnpm publish --filter @tietokilta/ilmomasiina-models --no-git-checks --access public
-          pnpm publish --filter @tietokilta/ilmomasiina-components --no-git-checks --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+            BRANDING_HEADER_TITLE_TEXT=${{ env.branding_header_title_text }}
+            BRANDING_FOOTER_GDPR_TEXT=${{ env.branding_footer_gdpr_text }}
+            BRANDING_FOOTER_GDPR_LINK=${{ env.branding_footer_gdpr_link }}
+            BRANDING_FOOTER_HOME_TEXT=${{ env.branding_footer_home_text }}
+            BRANDING_FOOTER_HOME_LINK=${{ env.branding_footer_home_link }}
 
+  # This is disabled on forks since you'll most likely need to modify it anyway for your usage
   deploy:
     name: Push update to App Service
     needs: docker
-    if: github.ref_type == 'branch'
+    if: github.ref_type == 'branch' && github.repository == 'Tietokilta/ilmomasiina'
     runs-on: ubuntu-latest
     environment: production
     steps:
@@ -125,4 +90,4 @@ jobs:
       uses: azure/webapps-deploy@v2
       with:
         app-name: tik-ilmo-${{ github.ref_name }}-app
-        images: 'ghcr.io/tietokilta/ilmomasiina:${{ github.ref_name }}'
+        images: '${{ env.docker_tag }}:${{ github.ref_name }}'

.github/workflows/npm-build.yml

@@ -0,0 +1,59 @@
+name: Publish JS packages
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  npm:
+    name: Publish JS packages
+    if: github.ref_type == 'tag' && github.repository == 'Tietokilta/ilmomasiina'
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      -
+        name: Check out the repo
+        uses: actions/checkout@v3
+      -
+        uses: pnpm/action-setup@v2
+        with:
+          version: 7
+      -
+        name: Setup Node.js for NPM
+        uses: actions/setup-node@v3
+        with:
+          registry-url: 'https://registry.npmjs.org'
+          node-version: '16'
+          cache: 'pnpm'
+      -
+        name: Install dependencies
+        run: |
+          npm install -g pnpm@7
+          pnpm install --frozen-lockfile --ignore-scripts
+      -
+        name: Build packages
+        run: |
+          pnpm run --filter @tietokilta/ilmomasiina-models build
+          pnpm run --filter @tietokilta/ilmomasiina-components build
+      -
+        name: Publish to NPM
+        run: |
+          pnpm publish --filter @tietokilta/ilmomasiina-models --no-git-checks --access public
+          pnpm publish --filter @tietokilta/ilmomasiina-components --no-git-checks --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      -
+        name: Setup Node.js for GitHub Packages
+        uses: actions/setup-node@v3
+        with:
+          registry-url: 'https://npm.pkg.github.com'
+      -
+        name: Publish to GitHub Packages
+        run: |
+          pnpm publish --filter @tietokilta/ilmomasiina-models --no-git-checks --access public
+          pnpm publish --filter @tietokilta/ilmomasiina-components --no-git-checks --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/README.md

@@ -4,6 +4,7 @@ This folder contains documentation files for Ilmomasiina.
 
 If you're interested in using Ilmomasiina for your purposes, these might be for you:
 - [Installation](installation.md) of a new instance
+- [Customization](installation.md#customization) with your organization's text, colors etc.
 - [Migration](migration.md) from the Athene version to 2.0.0 and from there to later versions
 - [Hacking Ilmomasiina](hacking.md) to suit your purposes