Short Description of the issue

Provide a downloadable version of the documentation (maybe a pdf)

We should provide guidance/example on how to assess the performance of a cloud site, it would be useful to understand what can be expected from a site and also to help diagnose/troubleshoot deployment problems.

Some pointers:

• https://github.com/GoogleCloudPlatform/PerfKitBenchmarker
• https://cloud.google.com/compute/docs/benchmarks-linux
• https://phoronix-test-suite.com/

Example:

# Using sysbench
sudo apt-get install sysbench
sysbench --test=cpu --cpu-max-prime=20000 run
# Using phoronix test suite
sudo apt-get install phoronix-test-suite
phoronix-test-suite list-available-suites
# Chose one, and run it.
phoronix-test-suite run pts/cpu 

It should be clearly stated that HTTPS is required for Cloud middleware configuration.
It could be added in clear prerequisites section explaining what is the requested the status of the cloud site (https and possibly other requirements).

Moved from EGI-Federation/fedcloud-integration-documentation#36

The currently available search field is not working, example: https://docs.egi.eu/search/?q=training

Search should be fixed or disabled.

Docsy documentation: https://www.docsy.dev/docs/adding-content/navigation/

Short Description of the issue

Get the whole documentation ready to be announced by providing some content in the existing placeholders.

Summary of proposed changes

Short Description of the issue

Workload manager doc contained few details that could worth to record.
Copying here just to avoid loosing them.

Summary of proposed changes

Install your credentials

$ mkdir -p $HOME/.globus
$ chmod 700 $HOME/.globus
$ openssl pkcs12 -in $HOME/MyCertificate \ -clcerts -nokeys -out $HOME/.globus/usercert.pem
$ openssl pkcs12 -in $HOME/MyCertificate\ -nocerts -out $HOME/.globus/userkey.pem
$ chmod 600 $HOME/.globus/usercert.pem $HOME/.globus/userkey.pem ```

Document who should be responsible of reviewing which part of the documentation (Service owner + someone else from TST or CST?).

On the Check-in page for Service Providers: eduperson_entitlement and edu_person_entitlements mentioned at different places, and this is confusing for service providers willing to connect their services via OIDC.
@nikosev, @ioigoume could you please check this to be sure that it's crystal clear?

Thanks!

Contributing guide: document usual and accepted way to adapt linter behaviour.
Example:

• adding line length check exception for tables (see #141 (review))

<!-- markdownlint-disable line-length -->
| Action           | rOCCI                                                                                                                | OpenStack                                                                                |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| List images      | `occi -a list -r os_tpl`                                                                                             | `openstack image list`                                                                   |
<!-- markdownlint-enable line-length -->

• adding inline-html exceptions for HTML tags in tables like <ul>, <ol> and <li> (see #141 (comment)):

<!-- markdownlint-disable line-length no-inline-html -->
Random text including HTML <span class="fritghtening">tags</span>.
<!-- markdownlint-enable line-length no-inline-html -->

Currently the deploy.sh script can be used to deploy the hugo output, but ideally we should automate deployment of site when a PR is merged. Travis could be used for this.

Short Description of the issue

Links should be periodically checked (specially those external to docs.egi.eu). See EGI-Federation/fedcloud-catchall-operations#24 (comment)

Summary of proposed changes

Add periodic action on link checking

We should document the management of OpenStack security groups.
Typically a user may want to deploy a service on a virtual machine and access is via something like HTTPS, we should document how to do this.

• https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/security-group.html
• https://docs.openstack.org/nova/queens/admin/security-groups.html

Provide/collect a list of technical resources that would be relevant for EGI participants and EGI Foundation members to go forward/learn more/share knowledge.

This would include things like:

• https://devhints.io/
• https://tldr.sh/
• https://developers.google.com/tech-writing
• https://landing.google.com/sre/books/
• https://roadmap.sh/devops

We need to find an appropriate way/place for publishing this.

Add some documentation explaining how users can contribute via the various possiblities:

• git fork / clone / PR workflow
• PR from the browser

Currently CAs and CRLs bundles have to be managed manually for HAproxy (cf. EGI-Federation/fedcloud-integration-documentation#28 and https://egi-federated-cloud-integration.readthedocs.io/en/latest/openstack.html#pre-requisites).
Ideally it should be automated using fetch-crl and yum hooks.

Automatic managing of CRLs bundle

Proposed solution by @dlgroep.

CRLs bundle should be updated after each fetch-crl passes. The postexec hook could be use with a script using cat and reloading HAproxy:

 #!/bin/sh
 cat "$5"/*.r0 > "$5"/igtf-crls-bundle.pem
 systemctl reload haproxy.service

Automatic managing of CAs bundle

Possible solutions

• Using a cron job with cat and reload (like every 6 hours) (proposed by @dlgroep)
• Using a yum-plugin-post-transaction-actions.noarch triggering on any change on one of the ca_* packages. (proposed by @msalle)

Moved from EGI-Federation/fedcloud-integration-documentation#30

This issue is about registration of FedCloud sites within GOCDB

• Registration in GOCDB is documented but this should be linked from a/multiple steps within the integration docs so that it's more clear for users when/how to do this.

Moved from EGI-Federation/fedcloud-integration-documentation#19

• Make easier to understand the GOCDB site-related requirements of joining FedCloud, for the time being registration of the new/existing site in GOCDB is covered in https://egi-federated-cloud-integration.readthedocs.io/en/latest/registration.html but it should be introduced/moved/linked from something like https://egi-federated-cloud-integration.readthedocs.io/en/latest/requirements.html so that site admins will notice it eatlier.

Moved from EGI-Federation/fedcloud-integration-documentation#48

• What about the FedCloud scope?

Moved from EGI-Federation/fedcloud-integration-documentation#6

See https://docsyjustdocs.netlify.app/ and https://github.com/lisaFC/justdocs/.

Points to check:

• hiding chlidren pages from page footer
• vote option at bottom of page (useful? yes/no)
• display of current entry in menu

Add .DS_Store (and other relevant files) to .gitignore.

Moved from EGI-Federation/fedcloud-integration-documentation#3

Short Description of the issue

Document what it provides and how to use it

Leverage the GitHub code owners feature to assign some PR to the various relevant people.

https://github.blog/2017-07-06-introducing-code-owners/

Automatic testing should ensure that there are no broken links.

Access/authorisation schemes of all central services should be clearly documented, currently we mainly rely on people's memory or service admins and while for some services this information may be buried in various places it's hard to find it so it's costly in time and error prone.
Example: secmon.egi.eu is only accessible by users having the NGI Security officer role.

Add installation with CMD documentation

We should ensure that documentation in wiki.egi.eu has been moved here (if relevant) and properly marked as obsolete.

List of pages to move/obsolete/replace:

https://wiki.egi.eu/wiki/EGI_Opendata_platform

Initial issue was EGI-Federation/datahub-documentation#5

Moved from EGI-Federation/fedcloud-integration-documentation#8

Update references to EGI-Foundation GitHub organisation to use EGI-Federation

https://nvuillam.github.io/mega-linter/
https://nvuillam.github.io/mega-linter/#mega-linter-vs-super-linter

Mega-Linter can automatically apply fixes performed by linters, and push them to the same branch, or create a Pull Request that you can validate
This is pretty handy, especially for linter errors related to formatting (in that case, you don’t have any manual update to perform)

Short Description of the issue

Update the README with clear instructions on how to install dependencies and build the site

Summary of proposed changes

We need to properly document, check and enforce line length

Short Description of the issue

Define actual(working) versions of components at the integration documentation

Summary of proposed changes

Would be nice to see at the integration documentation page the actual versions of components with links to dockerhub. Or in general create additional page how to start all components via docker form @enolfc repo. If needed I can try to prepare draft.

Short Description of the issue

Add information available at https://docs.google.com/document/d/1FGt15nxZU0Atz6oLxz5sSH_ePU0V-qV132rS1dqzuvA/edit#

Summary of proposed changes

Add some automated testing/validation using Travis.

In order to have a clear markdown styleguide that we can enforce using automated tools.

Hugo is using goldmark to parse and render markdown.
It's compliant with CommonMark.
GitHub Flavored Markdown is based on CommonMark.

So we need:

• a style guide compliant with CommonMark
• a linter able to enforce this when testing
• ideally an auto formatter that can be used with VIM and IDE

Some style guides and documentation about markdown:

• https://github.github.com/gfm/
• https://spec.commonmark.org/
• https://github.com/carwin/markdown-styleguide (could make a good basis for our style guide if we don' t find a perfect one already existing)
• https://daringfireball.net/projects/markdown/
• https://************.com/markdown-style-guide/
• https://guides.github.com/features/mastering-markdown/
• https://markdown-guide.readthedocs.io/en/latest/basics.html

Some linters:

• https://github.com/prettier/prettier/ (can do autoformat, but not meant to be configurable)
• https://github.com/remarkjs/remark-lint (really configurable, with a configuration for https://************.com/markdown-style-guide)
• https://github.com/markdownlint/markdownlint (AKA mdl gem, currently in use with Travis)
• https://github.com/DavidAnson/markdownlint/ (similar to mdl, but in nodejs)

This task is meant to collect the additional points to be documented in the contributing guide:

• using web interface or git rebase to merge changes from the upstream repository in case it was updated since the feature branch creation
• using alerts/info messages, see https://docs.egi.eu/users/cloud-compute/faq/#how-can-i-inject-my-public-ssh-key-into-the-machine
• including images (code snippet + naming of files),
• including code snippets
• README should also propose to use the live/nice version at https://docs.egi.eu/about/contributing/
• using git stash to backup changes uncommitted made to master, creating a feature branch and committing changes
• ensuring to save/commit quickly changes made to a PR via the web interface to avoid problems like #77 (comment)
• Style/contributing guide should clarify how services should be named (complete portfolio name) and acronyms used (only when providing a clear benefit and not for service n ames) (see #83 (comment))
• A link to style rules can be added to the pull request template

Short Description of the issue

We need some documentation on how IM and/or EC3 are used within fedcloud.

Short Description of the issue

Docs still talk about BDII needs to use the new stuff

Summary of proposed changes

Short Description of the issue

It would be nice to have some rendering of the proposed PRs so people can take a look how the changes will look on the server before merging.

Summary of proposed changes

https://www.docsy.dev/docs/adding-content/lookandfeel/#code-highlighting-with-prism seems to have benefits over the default setting, see google/docsy#370

Short Description of the issue

We should have some documentation on how to perform backups in cloud compute service

Summary of proposed changes

There should be a link (at least in the intro?) between the DataHub sections for users and providers.

Standard/common problems and instruction to help user debug their problems should be documented in something like a "troubleshooting" section.
It should probably include:

• checking that the user is in the appropriate VO/COU
• mention that there may be a need to link various identities or to ensure that it's always the same IdP that is used
• how to try to debug (using standard CLI/alternative tools)
• who to contact

Integrate stale issue and PR detection: https://github.com/actions/stale

Add EGI branding to the theme.

• @dscardaci suggested to remove the list of sections/subsections at the bottom of pages

Add code of conduct, copyright, authors and related files/templates for issues, PR,....

Move from Travis to github actions: we are experiencing long build delay using Travis, and according to changes in Travis management/strategy it may be safer to start looking at alternatives like GitHub actions.
https://docs.github.com/en/free-pro-team@latest/actions/quickstart

https://developer.okta.com/blog/2020/05/18/travis-ci-to-github-actions

https://github.com/marketplace/actions/hugo-setup

To be done:

• Mardkown linting
• Building site with hugo
• deploy on PR merge

Optimise image files, some are very large (much more than needed):

23MB of images is way too much.

GItHub action like https://github.com/marketplace/actions/imgcmp could be used to help with this.

In order to avoid bottleneck we need to setup at least two code owners per section.

Short Description of the issue

In https://docs.egi.eu/users/notebooks/data/ it says:

Every user of the EGI Notebooks catch-all instance has a 1GB persistent home to store any notebooks and associated data.

Is it 10GB instead?

Summary of proposed changes

I will open a PR to update it.

Short Description of the issue

Add documentation on egicli

Summary of proposed changes