{"id":22832834,"url":"https://github.com/ietf-tools/wiki","last_synced_at":"2025-04-23T21:25:42.540Z","repository":{"id":43410404,"uuid":"403691408","full_name":"ietf-tools/wiki","owner":"ietf-tools","description":"Custom Wiki.js Image for IETF wikis","archived":false,"fork":false,"pushed_at":"2024-01-20T20:12:43.000Z","size":136,"stargazers_count":3,"open_issues_count":1,"forks_count":8,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-30T03:41:16.488Z","etag":null,"topics":["authentication","wiki-js"],"latest_commit_sha":null,"homepage":"https://wiki.ietf.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ietf-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-09-06T16:32:18.000Z","updated_at":"2024-09-11T08:21:13.000Z","dependencies_parsed_at":"2024-01-20T02:33:00.956Z","dependency_job_id":"d6990572-fe8b-4c4a-96be-24a60350b548","html_url":"https://github.com/ietf-tools/wiki","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ietf-tools%2Fwiki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ietf-tools%2Fwiki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ietf-tools%2Fwiki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ietf-tools%2Fwiki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ietf-tools","download_url":"https://codeload.github.com/ietf-tools/wiki/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250516116,"owners_count":21443556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","wiki-js"],"created_at":"2024-12-12T21:09:43.190Z","updated_at":"2025-04-23T21:25:42.521Z","avatar_url":"https://github.com/ietf-tools.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \n\u003cimg src=\"https://raw.githubusercontent.com/ietf-tools/common/main/assets/logos/ietf-wikijs.svg\" alt=\"IETF Wiki.js\" height=\"125\" /\u003e\n    \n[![License](https://img.shields.io/github/license/ietf-tools/ietf-wikijs-auth)](https://github.com/ietf-tools/ietf-wikijs-auth/blob/main/LICENSE)\n\n##### Custom Wiki.js image for IETF wikis\n    \n\u003c/div\u003e\n\n---\n\nThis repository contains the custom IETF modules for Wiki.js, packaged into a docker container image.\n\n- [Deployment](#deployment)\n- [Modules](#modules)\n  - [Authentication - IETF Datatracker](#authentication---ietf-datatracker)\n    - [Initial Setup](#initial-setup)\n    - [Mappings](#mappings)\n  - [Rendering - IETF Custom](#rendering---ietf-custom)\n- [Docker Dev Environment](#docker-dev-environment)\n- [Running Tests](#running-tests)\n- [Releasing a New Build](#releasing-a-new-build)\n\n## Deployment\n\nOnce on the server:\n\n1. Create a new bridge network so that containers can find each other:\n```bash\ndocker network create wikinet\n```\n2. Create the wiki-update-companion container:\n```bash\ndocker run -d --name=wiki-update-companion -v /var/run/docker.sock:/var/run/docker.sock:ro --restart=unless-stopped -h wiki-update-companion --network=wikinet ghcr.io/ietf-tools/wiki-update-companion:latest\n```\n\nFor each Wiki.js instance:\n    \n1. Create a container, replacing the following `xyz123` values in the command below:\n\n```bash\ndocker run -d --name=xyz123 -e DB_HOST=xyz123 -e DB_PORT=5432 -e DB_PASS=xyz123 -e DB_USER=xyz123 -e DB_NAME=wiki -e UPGRADE_COMPANION_REF=xyz123 -h xyz123 -p 80:3000 -v /xyz123/mappings.json:/wiki/server/modules/authentication/ietf/mappings.json:ro --network=wikinet --restart=unless-stopped ghcr.io/ietf-tools/wiki:latest\n```\n\n- `--name=xyz123` -\u003e Name of the instance, should be unique for each container, e.g. `--name=wiki-ietf`\n- `-e DB_HOST=xyz123` -\u003e Hostname / IP of the PostgreSQL database server. (if database is on the host, see [Database on Localhost](#database-on-localhost) below.)\n- `-e DB_PORT=5432` -\u003e Port of the PostgreSQL database server.\n- `-e DB_USER=xyz123` -\u003e Username to connect to the PostgreSQL database server.\n- `-e DB_PASS=xyz123` -\u003e Password to connect to the PostgreSQL database server.\n- `-e DB_NAME=wiki` -\u003e Database name on the PostgreSQL server.\n- `-e UPGRADE_COMPANION_REF=xyz123` -\u003e Name reference to this container for the upgrade tool. Should be identical to the container name entered above (e.g. `-e UPGRADE_COMPANION_REF=wiki-ietf`).\n- `-h xyz123` -\u003e Hostname of the container instance. Should be identical to the container name entered above (e.g. `-h wiki-ietf`).\n- `-p 80:3000` -\u003e Change `80` to the desired port to expose. The port should be unique for each container. Do not change the `3000` value, this is the internal container port!\n- `-v /xyz123/mappings.json:...` -\u003e Path on the server (host) to the mappings.json file. This file will be mounted into the container.\n- `--network=wikinet` -\u003e Name of the bridge network created earlier.\n\n2. Ensure the container started correctly by running (replacing `xyz123` with the name of the container):\n```bash\ndocker logs xyz123 -f\n```\n\nThe output should include the line `HTTP Server: [ RUNNING ]`\n\n3. Add the proper config to your reverse-proxy software (e.g. nginx / apache) to point each domain to the correct port you exposed above.\n\n4. If this is a new Wiki.js instance, complete the setup by loading the domain name in your browser.\n\n### Database on localhost\n\nNote that you cannot use `localhost` or `127.0.0.1` as the `DB_HOST` value to communicate to a PostgreSQL server installed on the host itself, as localhost refers to the container itself, not the host. You must instead add the following to the docker run command *(note that there's nothing to replace in the command below, `host-gateway` is a special docker keyword!)*:\n\n```bash\n--add-host=host.docker.internal:host-gateway\n```\n\nThis will add a DNS entry in the container that automatically points to the Docker host IP address. You can then specify `host.docker.internal` as the host for the `DB_HOST` parameter.\n\n## Modules\n\n### Authentication - IETF Datatracker\n\n\u003e **Note**  \n\u003e The `mappings.json` provided in this repository is only an example and should be modified to match the target instance use case.\n\n#### Initial Setup\n\n1. Head to Wiki.js **Administration Area** and validate that all groups specified in `mappings.json` have been added under **Groups**. Missing groups are automatically created during initialization.\n2. Still under **Groups**, add the necessary page rules / permissions for all groups.\n\n    \u003e ***Note that groups must NOT be renamed. They must match exactly as they are in `mappings.json`.***\n3. Under **Authentication** settings add the strategy **IETF datatracker OpenID Connect**\n    * Enable *Allow self-registration*\n    * Complete the configuration with the IETF provider settings\n    * Ensure that the machine is reachable to the strategy *callback URL*\n\n#### Non-Docker Usage\n\nCopy the whole `ietf` folder under the path `server/modules/authentication/` of your wiki.js instance.\n\n#### Mappings\n\nThe mapping between IETF datatracker roles and wiki.js groups can be specified in the `mappings.json` file.\nThe format of the file is the following: \n```\n{\n    \"defaults\": Array of Strings,\n    \"groups\": Array of Strings,\n    \"mappings\": Object\n}\n```\n`defaults` contains the list of the groups that will be auto-added to any authenticated users, e.g.:\n\n```\n{\n    \"defaults\": [\"members\", \"users\"],\n    \"groups\": [],\n    \"mappings\": {\n        ...\n    }\n}\n```\n\n`groups` contains the list of the groups that will be automatically created if they don't already exist on initialization:\n\n```\n{\n    \"defaults\": [],\n    \"groups\": [\"iesg\", \"ietf-chairs\"],\n    \"mappings\": {\n        ...\n    }\n}\n```\n\n`mappings` has the following format:\n```\n{\n    \"defaults\": ...\n    \"groups\": ...\n    \"mappings\": {\n        \"roles\": {\n            \"groupname_1\": Array of Arrays,\n            \"groupname_2\": Array of Arrays,\n            \"groupname_3\": Array of Arrays,\n            ...\n        },\n        \"dots\": {\n            \"groupname_4\": Array of Strings,\n            ...\n        }\n    }\n}\n```\nAny element of an array `groupname` in the `roles` section is a tuple `[oidcRole, oidcGroup, ... ]` (as returned by the datatracker OIDC user-info API) that will match the `groupname` wiki.js group, e.g.:\n```\n...\n\"mappings\": {\n    \"roles\": {\n        \"admins\": [\n            [\n                \"ad\",\n                \"iesg\",\n                ...\n            ],\n            [\n                \"chair\",\n                \"ietf\",\n                ...\n            ],\n        ],\n        \"iesg\": [\n            [\n                \"ad\",\n                \"iesg\"m\n                ...\n            ],\n            [\n                \"execdir\",\n                \"ietf\",\n                ...\n            ]\n        ],\n        ...\n    }\n    ...\n}\n```\nBy using wildcards `*` you can omit any tuple element, e.g.:\n```\n\"mappings\": {\n    \"roles\": {\n        \"chairs\": [\n            [\n                \"chair\",\n                \"*\",\n                ...\n            ]\n        ],\n        \"iesg-users\": [\n            [\n                \"*\",\n                \"iesg\",\n                ...\n            ]\n        ],\n        ...\n    }\n    ...\n}\n```\nAny element of an array `groupname` in the mappings `dots` section is an array of strings `[dot1, dot2, ... ]` (as returned by the datatracker OIDC user-info API) that will match the `groupname` wiki.js group, e.g.:\n```\n\"mappings\": {\n    ...\n    \"dots\": {\n        \"chairs\": [ \"llc\", ... ],\n        ...\n    }\n    ...\n}\n```\n\nAny change to the mappings file requires a restart of the container while in dev mode.\n\n### Rendering - IETF Custom\n\nThis rendering module ensures that any references to RFC's or Internet Drafts are automatically linked to their corresponding Datatracker page.\n\nThis module should be enabled by default under the Administration Area \u003e Rendering \u003e HTML\n\n## Docker Dev Environment\n\n1. `docker-compose up`\n2. Complete the initial setup of wiki.js by connecting to `http://HOST:PORT` (default `PORT` is 1926)\n3. Create a homepage\n4. Head to wiki.js **Administration** settings and add the groups specified in `mappings.json`\n5. Create the group rules if you need to enforce the permission system\n6. Under **Authentication**, add the strategy **IETF datatracker OpenID Connect**\n    * Enable *Allow self-registration*\n    * Complete the configuration with the IETF provider settings\n    * Ensure that the machine is reachable to the strategy *callback URL*\n\n## Running tests\n\n```sh\nnpm install\nnpm run test\n```\n\n## Releasing a New Build\n\nTo release a new docker image, go to the **Actions** tab, select the **Build and Release** workflow and click **Run workflow**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fietf-tools%2Fwiki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fietf-tools%2Fwiki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fietf-tools%2Fwiki/lists"}