Creating a collection

Define the necessary metadata

First of all, define the scope and metadata of the collection:

  • Concise description of the collection topic (examples: Largest global social media, Most used social media in France, Dating apps, Platforms providing services to businesses…)
  • Collection name (3 words maximum, examples: Platform Governance Archive, France Élections, Dating, P2B Compliance Assessment…)
  • Collection ID (examples: pga, France-elections, dating, p2b-compliance…)
  • Terms language (examples: English, French, All EU languages…)
  • Terms jurisdiction (examples: EU, France, EEA, USA, global…)
  • Collection maintainer entity (name, logo, url)

Create repositories

Declarations

Create the collection declarations repository by using the demo-declarations repository as template:

  • Go to the demo-declarations repository
  • Click on the “Use this template” dropdown and select “Create a new repository”
  • Set the repository name to <collection_id>-declarations. For example: pga-declarations.
  • When redirected to the newly generated repository, wait a minute or two for the automatic setup to run. You can check the status of the first-time-setup GitHub action to make sure that everything ran fine.

Fill the about section

  • Click on the little cogwheel icon next to the “About” block.
  • Set the description to “Declarations for <collection_name>. Maintained by <maintainer>.”
  • Set website: https://opentermsarchive.org
  • Add the following tags: terms-of-service, terms-of-service-agreements, terms-and-conditions, open-terms-archive.
  • Uncheck “Releases”, “Packages” and “Environments”.

Define repository settings

These settings ease the whole contribution process.

  • In the “Pull Requests” section: check only the “Allow squash merging” option, and set it to “Default to pull request title and commit details”.
  • Enable “Allow auto-merge”.
  • Enable “Automatically delete head branches”.
  • In the “Branches” section: add a branch protection rule for main, check “Require status checks to pass before merging” and add validate_modified_declarations and validate_schema as required status checks.
  • In the “Actions” section, in the “General” submenu: select “Allow all actions and reusable workflows”.

Update README

  • Update the README file with proper metadata: topic, maintainers, jurisdictions, languages…

Update deployment inventory

  • Open the deployment/inventory.yml and set the server information: server IP, username, server fingerprint…

Snapshots

Create the snapshots repository by using the demo-snapshots repository as template:

  • Go to the demo-snapshots repository
  • Click on the “Use this template” dropdown and select “Create a new repository”
  • Set the repository name to <collection_id>-snapshots.
  • When redirected to the newly generated repository, wait a minute or two for the automatic setup to run. You can check the status of the first-time-setup GitHub action to make sure that everything ran fine.
  • Give write rights on the repo to the maintenance team.

Fill the “About” section

  • Set the description: “Documents snapshots for <collection_name>. Maintained by <maintainer>.”
  • Set website: https://opentermsarchive.org
  • Add the following tags: terms-of-service, terms-of-service-agreements, terms-and-conditions, open-terms-archive.
  • Uncheck “Releases”, “Packages” and “Environments”.

Define repository settings

These settings aim at minimising the otherwise overwhelming amount of information and click targets.

  • Features: uncheck “Wikis”, “Issues”, “Discussions” and “Projects”.
  • In the “Actions” section, in the “General” submenu: select “Disable actions”.

Versions

Create the versions repository by using the demo-versions repository as template:

  • Go to the demo-versions repository
  • Click on the “Use this template” dropdown and select “Create a new repository”
  • Set the repository name to <collection_id>-versions.
  • When redirected to the newly generated repository, wait a minute or two for the automatic setup to run. You can check the status of the first-time-setup GitHub action to make sure that everything ran fine.
  • Give write rights on the repo to the maintenance team.

Fill the “About” section

  • Set the description: “Terms versions for <collection_name>. Maintained by <maintainer>.”
  • Set website: https://docs.opentermsarchive.org/navigate-history/
  • Add the following tags: terms-of-service, terms-of-service-agreements, terms-and-conditions, open-terms-archive.
  • Uncheck “Packages” and “Environments”.

Define repository settings

These settings aim at minimising the otherwise overwhelming amount of information and click targets.

  • Features: uncheck “Wikis”, “Issues”, “Discussions” and “Projects”.
  • In the “Actions” section, in the “General” submenu: select “Disable actions”.

Set up GitHub maintenance teams

For collections to be included in the Open Terms Archive organisation only. For third parties, handle rights however you see fit.

  • Create a new collection team
  • Give it the name of the collection
  • Set as avatar the collection icon from the website
  • Set as description: “Maintainers of the <collection_name> collection”
  • Add selected members to the team
  • Add the declarations repository to the collection team, with “Maintain” access rights
  • Add the snapshots repository to the collection team, with “Triage” access rights (giving them more would enable them to corrupt data)
  • Add the versions repository to the collection team, with “Triage” access rights (giving them more would enable them to corrupt data)
  • Add the declarations, snapshots and versions repositories to the Bots team with “Write” access

Setup deployment

On the server

  • Connect to the server with ssh <username>@<host> (example usernames: debian, ubuntu…)
  • Create a new SSH key: ssh-keygen -q -N "" -f ~/.ssh/ota-deploy
  • Add the public key to authorized_keys: cat ~/.ssh/ota-deploy.pub >> ~/.ssh/authorized_keys
    • Copy the public key with cat ~/.ssh/ota-deploy.pub and keep it temporarily for the next steps
  • Add the private key to the SSH authentication agent: ssh-add ~/.ssh/ota-deploy (start the SSH agent before if necessary with eval \ssh-agent -s``)
    • Copy the private key with cat ~/.ssh/ota-deploy and keep it temporarily for the next steps

Note: user must have the right to sudo.

On GitHub declarations repository settings

Create the following secrets:

  • SERVER_FINGERPRINT: obtained with ssh-keyscan -t ed25519 <host>
  • SERVER_SSH_KEY: use the previously generated server private key

On declarations repository

Fill deployment/inventory.yml:

  • <host> (example: 162.19.74.224)
  • ansible_user: <username> (example: debian)
  • ed25519_fingerprint: <server_ssh_fingerprint> (example: AAAAC3NzaC1lZDI1NTE5AAAAIJkjE1KIbUcoClK+iKLR5ZvmdXMD/eXWghHdenFeJz4c obtained with ssh-keyscan -t ed25519 <host>)

Test

Via GitHub Actions

  • Check that the deploy action ran properly on the declarations repository.

Locally

To test deployment from your local machine, your SSH keys must be authorized to connect to the server.

  • cd <path/to/><collection_id>-declarations/deployment
  • ansible-playbook opentermsarchive.deployment.deploy