📗 Climate Gains Tech Manual

Documentation & Support
1

This is (meant to be …) the one-and-only entry point for the Climate Gains tech stack documentation.

A more navigable and potentially more recent version of this document is provided in the Climate Gains Tech notebook on Noteshub. This wiki is simply an exported version of the Noteshub notebook, so use the latter if you have access.

Updating this manual

  1. Edit the Climate Gains Tech Noteshub notebook.

  2. Copy & paste its content to a LibreOffice document and save it as a .odt file. The whole “Credentials” must be omitted when copy-pasting a new version into there, because this wiki is public.

  3. Use Pandoc convert to Markdown:

    pandoc --from odt --to markdown_strict --standalone \
  --wrap=none --atx-headers file.odt -o file.odt.md

  4. Copy the Markdown file to the clipboard: xclip -sel c file.odt.md

  5. Edit this wiki, remove the content below the next line, and replace it by pasting the copied Markdown file.

  • Project Docs

    • –––––– Central Docs ––––––

    • :bulb: Tech Notebook

      • Contained in the Noteshub notebook “Climate Gains Tech”. The notebook is end-to-end encrypted; to access it, you need a passphrase that you can only get via a secure channel from @matthias. Such passphrase must not be stored anywhere online, as it would give access to a good part of our infrastructure. (Noteshub is a knowledge management solution developed by @daniel, which we test and use here.)

    • Tech Manual

      • See: Discourse forum topic “Climate Gains Tech Manual”. A copy-pasted version of the Tech Notebook, to make it more accessible. The “Credentials” section must be omitted when copy-pasting a new version into there!

    • ––– Single-Artefact Docs –––

    • Climage Gains App

    • Backend Dashboard

      • README

        • []

    • Backend API

      • Technologies

      • API docs (“Swagger”)

      • API Requirements

      • :bulb: API Overview

        • Climate Actions: list

        • :bulb: Climate Actions: show

          • Formally called “Climate Actions Opportunity Index”.
          • Current dummy implementation: see: actions.json.

        • Climate Actions: list bookmarked

        • Users: login

        • User Profile: show

        • User profile: show payment information

        • Video Inbox: list

        • FAQ: list

        • FAQ: show

        • Applications: list

        • Applications: create

        • Documents: list

        • Suppliers: list

        • Search: query

      • :pencil2: README

        • []

    • Forum

  • Component Docs

    • API documentation system

      • OpenAPI Specification (OAS)

        • A standard for API documentation of all RESTful HTTP APIs. There are related standards for documenting asyncAPIs, JSON schemas etc. as well.
        • Developed by the OpenAPI Initiative.

      • Swagger Open Source Tools

        • Tools that implement the OpenAPI Specification and can be used, among other things, to provide the API documentation as part of the project’s website.

  • Features

    • Done

    • Current

      • Location radius for Climate Actions

        • A Climate Action needs a “meta → location → radius” element in the API. Because sometimes the location is a whole country, or a region, or similar. Then at least an approx. location and can be shown on a map. Limiting it to various levels of political boundaries would be even better, but for much later.

      • Host organization name for Climate Actions

        • A Climate Action needs a “host organization” name that is listed in the overview.
        • See at 0:20 in the wireframes video.

    • Planned

  • Instructions

    • How to use the API docs of the ITMO API software offline?

      • You can simply save the API docs page using the SingleFile browser extension. It seems to work that way, and will not issue any requests to a server when using this saved version later (checked with Forefox Inspector).

    • How to enable the API docs in the ITMO API software?

      • Source / Reasoning

        • "We use https://www.openapis.org/ as documentation standard and we expose a https://swagger.io/ to viewable. […] SWAGGER is reachable through http://localhost:3000/docs " (source)
        • There is no need to disable API token bearer authentication to the Swagger UI (see file src/swagger.ts, the .addBearerAuth() call). This is an alternative authentication option, provided in addition to HTTP Basic Auth (see file src/main.ts). It may be helpful for automated access to the API docs, while HTTP Basic Auth is most useful to humans.
        • There is no need to serve Swagger UI explicitly on a HTTP URL rather than a HTTPS URL. It is probably served with a relative URL, which is by default open to both schemes. If that would be necessary, see this solution.

      • Make sure your ITMO API can be accessed through HTTPS.

      • In file api/.env, set:
        export SWAGGER_ENABLED=true
        […]
        export SWAGGER_BASICAUTH_USER=your_username
        export SWAGGER_BASICAUTH_PASSWORD=your_password

      • Disable the “helmet” package. In file api/main.ts, disable the following two lines:
        import helmet from ‘helmet’;
        app.use(helmet());

        • Helmet is a package that tries to “fix” HTTP security issues by setting some headers (esp. CORS). This includes a header that auto-upgrades every HTTP request to a HTTPS request, even when entering a HTTP URL into the browser’s address bar.
        • The ITMO software will usually be served behind a reverse proxy, in which case it cannot (reasonably) use HTTPS for the connection between proxy and Node.js server. In that case, the Helmet-enforced policies make requests with the HTTP scheme fail, as the upgrading to HTTPS does not succeed. So we are forced to change the headers provided by Helmet, which is most easily done by just disabling the plugin.
        • A better alternative to completely disabling it is probably contained in the answers to this question.

      • Restart the API server software: cd api/; npm run start:dev

      • Access the Swagger UI with your chosen HTTP Basic username and password and your configured port at: http://example.com:3000/docs.
        If you use a Reverse Proxy setup, use https:// and omit the port, means you will access the site through the proxy. Direct access to the un-proxied site should not be possible for security reasons, as the un-proxied site does not use SSL.

  • Instructions for Emergencies