egi-federation / documentation Goto Github PK
View Code? Open in Web Editor NEWSources to build EGI documentation site.
Home Page: https://docs.egi.eu/
License: MIT License
Sources to build EGI documentation site.
Home Page: https://docs.egi.eu/
License: MIT License
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
Leverage the GitHub code owners feature to assign some PR to the various relevant people.
Add EGI branding to the theme.
Add installation with CMD documentation
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.
Links should be periodically checked (specially those external to docs.egi.eu). See EGI-Federation/fedcloud-catchall-operations#24 (comment)
Add periodic action on link checking
Add code of conduct, copyright, authors and related files/templates for issues, PR,....
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:
<!-- markdownlint-disable line-length -->
| Action | rOCCI | OpenStack |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| List images | `occi -a list -r os_tpl` | `openstack image list` |
<!-- markdownlint-enable line-length -->
<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 -->
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
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?
I will open a PR to update it.
There should be a link (at least in the intro?) between the DataHub sections for users and providers.
We need to properly document, check and enforce line length
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:
We need to find an appropriate way/place for publishing this.
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.
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.
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.
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
Possible solutions
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
Document who should be responsible of reviewing which part of the documentation (Service owner + someone else from TST or CST?).
We need some documentation on how IM and/or EC3 are used within fedcloud.
Add some documentation explaining how users can contribute via the various possiblities:
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.
See https://docsyjustdocs.netlify.app/ and https://github.com/lisaFC/justdocs/.
Points to check:
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.
Get the whole documentation ready to be announced by providing some content in the existing placeholders.
Provide a downloadable version of the documentation (maybe a pdf)
Update references to EGI-Foundation GitHub organisation to use EGI-Federation
Standard/common problems and instruction to help user debug their problems should be documented in something like a "troubleshooting" section.
It should probably include:
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/
In order to avoid bottleneck we need to setup at least two code owners per section.
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:
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
Automatic testing should ensure that there are no broken links.
https://www.docsy.dev/docs/adding-content/lookandfeel/#code-highlighting-with-prism seems to have benefits over the default setting, see google/docsy#370
Docs still talk about BDII needs to use the new stuff
Add some automated testing/validation using Travis.
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)
Update the README with clear instructions on how to install dependencies and build the site
Add documentation on egicli
Integrate stale issue and PR detection: https://github.com/actions/stale
Document what it provides and how to use it
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:
This task is meant to collect the additional points to be documented in the contributing guide:
git rebase
to merge changes from the upstream repository in case it was updated since the feature branch creationgit stash
to backup changes uncommitted made to master, creating a feature branch and committing changesAdd information available at https://docs.google.com/document/d/1FGt15nxZU0Atz6oLxz5sSH_ePU0V-qV132rS1dqzuvA/edit#
Add .DS_Store (and other relevant files) to .gitignore.
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:
Some style guides and documentation about markdown:
Some linters:
This issue is about registration of FedCloud sites within GOCDB
Moved from EGI-Federation/fedcloud-integration-documentation#19
Moved from EGI-Federation/fedcloud-integration-documentation#48
Moved from EGI-Federation/fedcloud-integration-documentation#6
We should have some documentation on how to perform backups in cloud compute service
Workload manager doc contained few details that could worth to record.
Copying here just to avoid loosing them.
$ 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 ```
Define actual(working) versions of components at the integration documentation
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.