diff --git a/.vscode/extensions.json b/.vscode/extensions.json index faa2964bf..e4a2a577d 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -4,6 +4,7 @@ "DavidAnson.vscode-markdownlint", "ms-python.python", "redhat.vscode-yaml", + "samuelcolvin.jinjahtml", "tamasfe.even-better-toml", "yzhang.markdown-all-in-one", ] diff --git a/.vscode/settings.json b/.vscode/settings.json index a9b80dd27..dca66e130 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -16,6 +16,15 @@ "editor.wordWrap": "on", "files.eol": "\n" }, + "[jinja-md]": { + "editor.defaultFormatter": "samuelcolvin.jinjahtml", + "editor.formatOnSave": true, + "editor.indentSize": 4, + "editor.insertSpaces": true, + "editor.tabSize": 4, + "editor.wordWrap": "on", + "files.eol": "\n" + }, "[json]": { "editor.defaultFormatter": "vscode.json-language-features", "editor.formatOnSave": true, @@ -90,12 +99,12 @@ "editor.tabSize": 2, "files.eol": "\n" }, - "files.insertFinalNewline": true, - "files.trimFinalNewlines": true, - "files.trimTrailingWhitespace": true, "files.exclude": { "**/node_modules/*": true }, + "files.insertFinalNewline": true, + "files.trimFinalNewlines": true, + "files.trimTrailingWhitespace": true, "files.watcherExclude": { "**/node_modules/*": true }, @@ -107,5 +116,19 @@ "markdown.extension.tableFormatter.enabled": false, "markdown.extension.toc.updateOnSave": false, "markdown.validate.unusedLinkDefinitions.enabled": "warning", - "redhat.telemetry.enabled": false + "redhat.telemetry.enabled": false, + "yaml.customTags": [ + "!ENV scalar", + "!ENV sequence", + "!relative scalar", + "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg", + "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji", + "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format", + "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping" + ], + "yaml.schemas": { + "./res/.grid_cards_schema.yml": "/res/grid_cards.yml", + "./res/.announcements_schema.yml": "/res/announcements.yml" + // "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml" + } } diff --git a/build_env.yml b/build_env.yml index 8cc451ceb..a0843c8e0 100644 --- a/build_env.yml +++ b/build_env.yml @@ -3,18 +3,13 @@ dependencies: - conda-forge::click=8.2.1 - conda-forge::jinja2=3.1.6 - conda-forge::libffi=3.4.6 - - conda-forge::markdown=3.8.0 - conda-forge::markupsafe=3.0.2 # Not semver, be cautious - conda-forge::mergedeep=1.3.4 - - conda-forge::mkdocs=1.6.1 - - conda-forge::mkdocs-material=9.6.14 - - conda-forge::mkdocs-material-extensions=1.3.1 - conda-forge::numpy=2.2.6 - conda-forge::pandas=2.3.0 - conda-forge::pandoc=3.7.0.2 - conda-forge::pip=25.1.1 - conda-forge::pygments=2.19.1 - - conda-forge::pymdown-extensions=10.15 # Not semver, be cautious - conda-forge::pypandoc=1.15 - conda-forge::pyparsing=3.0.9 - conda-forge::python=3.13.3 @@ -31,11 +26,17 @@ dependencies: - conda-forge::yaml=0.2.5 - conda-forge::yamllint=1.37.1 - pip: + - jinja2-workarounds==0.1.0 + - markdown==3.8.0 - mkdocs-gen-files==0.5.0 - mkdocs-glightbox==0.3.7 - mkdocs-git-revision-date-localized-plugin==1.2.6 + - mkdocs-material==9.6.14 - mkdocs-redirects==1.2.1 - - mkdocs-table-reader-plugin==2.0.3 + - mkdocs-table-reader-plugin==3.1.0 - linkchecker==10.4.0 - pre-commit==3.7.1 + - pymdown-extensions==10.8.1 # Not semver, be cautious + - git+https://github.com/wwarriner/mkdocs-macros-plugin@d445c98dcc14ecae48ddf53b4758f3942ed706b8 + - git+https://github.com/uabrc/mkdocs@888fd28f92a320352f63600c24635231a42e5fac # new - git+https://github.com/uabrc/mkdocs-title-casing-plugin.git@stable diff --git a/docs/_macro/link.md.j2 b/docs/_macro/link.md.j2 new file mode 100644 index 000000000..35f89e792 --- /dev/null +++ b/docs/_macro/link.md.j2 @@ -0,0 +1,3 @@ +{% macro link(text, path) -%} +[{{ text }}]({{ path | normalize_link }}) +{%- endmacro %} diff --git a/docs/_macro/support.md.j2 b/docs/_macro/support.md.j2 new file mode 100644 index 000000000..ca618f2ca --- /dev/null +++ b/docs/_macro/support.md.j2 @@ -0,0 +1,65 @@ +{% from "_macro/link.md.j2" import link %} + +{% macro contact_support_link() -%} +{{ link("Contact Support", "help/support.md") }} +{%- endmacro %} + +{% macro _header(title, level) -%} +{% for i in range(level) -%}{{- "#" -}}{%- endfor %} {{ title }} +{%- endmacro %} + +{% macro help_header(level) -%} +{{ _header("Help", level) }} +{%- endmacro %} + +{% macro support_card_email() -%} +{{ + renderer.render_cards( + cards.support.email, + ) +}} +{%- endmacro %} + +{% macro support_card_office_hours() -%} +{{ + renderer.render_cards( + cards.support.office_hours, + ) +}} +{%- endmacro %} + +{% macro support_card_servicenow() -%} +{{ + renderer.render_cards( + cards.support.servicenow, + ) +}} +{%- endmacro %} + +{% macro support_card_statuscast() -%} +{{ + renderer.render_cards( + cards.support.statuscast, +) +}} +{%- endmacro %} + +{% macro support_cards_direct() -%} +{{ + renderer.render_cards( + cards.support.email, + cards.support.office_hours, + ) +}} +{%- endmacro %} + +{% macro support_cards_all() -%} +{{ + renderer.render_cards( + cards.support.email, + cards.support.office_hours, + cards.support.servicenow, + cards.support.statuscast, + ) +}} +{%- endmacro %} diff --git a/docs/_template/base_help_section.md.j2 b/docs/_template/base_help_section.md.j2 new file mode 100644 index 000000000..56b996d42 --- /dev/null +++ b/docs/_template/base_help_section.md.j2 @@ -0,0 +1,4 @@ +{% from "_macro/support.md.j2" import support_cards_direct, help_header with context %} +{{ help_header(2) }} + +{{ support_cards_direct() }} diff --git a/docs/_template/uab_employee_use_only.md.j2 b/docs/_template/uab_employee_use_only.md.j2 new file mode 100644 index 000000000..aadf0b757 --- /dev/null +++ b/docs/_template/uab_employee_use_only.md.j2 @@ -0,0 +1,3 @@ +!!! note + + These instructions are intended for use by UAB employees. diff --git a/docs/account_management/res/user_responsibilities.csv b/docs/account/_res/user_responsibilities.csv similarity index 99% rename from docs/account_management/res/user_responsibilities.csv rename to docs/account/_res/user_responsibilities.csv index 977ecf746..274d84e22 100644 --- a/docs/account_management/res/user_responsibilities.csv +++ b/docs/account/_res/user_responsibilities.csv @@ -1,5 +1,5 @@ -Category,User Group,Requirements,Responsibilities -UAB Employees,UAB Campus and UAB Medicine Faculty/Staff and Postdocs,Must have an active BlazerID,[Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).
For Lab PIs and Core Directors please refer [Lab PIs responsibilities](#lab-pis). -UAB Students,All UAB Campus and UAB Medicine Students,Must have an active BlazerID,[Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities). -External Collaborators,All sponsored by UAB Employee,Must be sponsored by UAB employee
Must have XIAS email address,Collaborators' Responsibility:
  - [Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).
  - [Create a XIAS Guest Account](../account_management/xias/guest_instructions.md#create-account).
Sponsor's Responsibility:
  - Sponsor is accountable for collaborators actions on UAB systems.
  - Please refer to [external collaborators](./xias/index.md#external-collaborator-xias-accounts) page. -Lab PIs,All Lab PIs and Core Directors,Must have an active BlazerID,Data Management and Storage:
  - Periodically check group membership is correct.
  - Periodically check access controls to directories/buckets are correct.
  - Moving unused data to LTS or external archival solutions.
  - Managing backup plans.
OpenStack Projects:
  - Periodically check group membership is correct.
  - Periodically check unused resources are released.
PIs are also responsible to:
  - Regularly reviewing membership permissions and access control.
  - Ensure students are aware about [FERPA-protected project metadata](https://www.uab.edu/registrar/ferpa/faculty-staff).
  - [Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities). +Category,User Group,Requirements,Responsibilities +UAB Employees,UAB Campus and UAB Medicine Faculty/Staff and Postdocs,Must have an active BlazerID,[Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).
For Lab PIs and Core Directors please refer [Lab PIs responsibilities](#lab-pis). +UAB Students,All UAB Campus and UAB Medicine Students,Must have an active BlazerID,[Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities). +External Collaborators,All sponsored by UAB Employee,Must be sponsored by UAB employee
Must have XIAS email address,Collaborators' Responsibility:
  - [Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).
  - [Create a XIAS Guest Account](../account_management/xias/guest_instructions.md#create-account).
Sponsor's Responsibility:
  - Sponsor is accountable for collaborators actions on UAB systems.
  - Please refer to [external collaborators](./xias/index.md#external-collaborator-xias-accounts) page. +Lab PIs,All Lab PIs and Core Directors,Must have an active BlazerID,Data Management and Storage:
  - Periodically check group membership is correct.
  - Periodically check access controls to directories/buckets are correct.
  - Moving unused data to LTS or external archival solutions.
  - Managing backup plans.
OpenStack Projects:
  - Periodically check group membership is correct.
  - Periodically check unused resources are released.
PIs are also responsible to:
  - Regularly reviewing membership permissions and access control.
  - Ensure students are aware about [FERPA-protected project metadata](https://www.uab.edu/registrar/ferpa/faculty-staff).
  - [Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities). diff --git a/docs/account/_template/authorization.md.j2 b/docs/account/_template/authorization.md.j2 new file mode 100644 index 000000000..ed1b126f5 --- /dev/null +++ b/docs/account/_template/authorization.md.j2 @@ -0,0 +1,20 @@ +# Research Computing System (RCS) Authorization + +## Who Is Eligible For RCS Authorization? + +Due to security requirements imposed by US federal funding agencies, RCS authorization is limited to specific UAB affiliations. If you are in one of the following categories, you are eligible to access RCS. + +- UAB Campus Employee +- UAB Campus Student +- UAB Medicine Employee +- XIAS Guest with UAB Campus Employee Sponsor + +Other affiliations, including alumni and volunteer, are not authorized to access RCS. + +## What Else Is Required for RCS Authorization? + +Being in one of the categories above is necessary for RCS authorization, but not sufficient. Researchers are also expected to adhere to all relevant and prevailing policies, regulations, and laws, at all times. + +## Where Can I Read More About Policies? + +LINK GOES HERE diff --git a/docs/account/_template/first_time_2fa.md.j2 b/docs/account/_template/first_time_2fa.md.j2 new file mode 100644 index 000000000..16e9be645 --- /dev/null +++ b/docs/account/_template/first_time_2fa.md.j2 @@ -0,0 +1,4 @@ + +!!! security + + If this is your first time logging in, you will first need to setup [Two-Factor Authentication](https://www.uab.edu/it/home/security/2-factor). diff --git a/docs/account/_template/first_time_vpn.md.j2 b/docs/account/_template/first_time_vpn.md.j2 new file mode 100644 index 000000000..d4d4cbafa --- /dev/null +++ b/docs/account/_template/first_time_vpn.md.j2 @@ -0,0 +1,4 @@ + +!!! security + + If this is your first time logging in, you will first need to setup [UAB Campus Network VPN Access](https://www.uab.edu/it/home/tech-solutions/network/vpn). VPN access requires [Two-Factor Authentication](https://www.uab.edu/it/home/security/2-factor). diff --git a/docs/account/_template/not_affiliated_with_uab.md.j2 b/docs/account/_template/not_affiliated_with_uab.md.j2 new file mode 100644 index 000000000..68745908e --- /dev/null +++ b/docs/account/_template/not_affiliated_with_uab.md.j2 @@ -0,0 +1,2 @@ +{% from "_macro/link.md.j2" import link %} +Not affiliated with UAB? To access RCS, you must first {{ link("Create an External Collaborator (XIAS) Account", "account/xias/index.md") }}. diff --git a/docs/account/_template/responsibilities_for_all.md.j2 b/docs/account/_template/responsibilities_for_all.md.j2 new file mode 100644 index 000000000..ab75e676e --- /dev/null +++ b/docs/account/_template/responsibilities_for_all.md.j2 @@ -0,0 +1,4 @@ +- Adherence to [UAB IT policies](https://www.uab.edu/it/home/policies). +- Adherence to research data security requirements, when applicable (e.g., NIST 800-171, HIPAA, etc.) +- [Responsible Conduct of Research (RCR) training](https://www.uab.edu/research/home/responsible-conduct-of-research) completed. +- Fair and appropriate use of RCS platforms and services. diff --git a/docs/account/_template/responsibilities_security.md.j2 b/docs/account/_template/responsibilities_security.md.j2 new file mode 100644 index 000000000..cc17991f2 --- /dev/null +++ b/docs/account/_template/responsibilities_security.md.j2 @@ -0,0 +1,4 @@ +- Research data security + - Awareness, understanding, and application of relevant security standards, e.g., NIST 800-171, HIPAA, FERPA, etc. + - Know which requirements apply to each of your grants. + - Manage administrative controls for members of shared allocations. diff --git a/docs/account/_template/uab_medicine_credentials.md.j2 b/docs/account/_template/uab_medicine_credentials.md.j2 new file mode 100644 index 000000000..8374130e4 --- /dev/null +++ b/docs/account/_template/uab_medicine_credentials.md.j2 @@ -0,0 +1,3 @@ +!!! important + + UAB Medicine employees must authenticate with their BlazerID credentials. These are different from your UAB Medicine credentials. diff --git a/docs/account/_template/xias_need_sponsor.md.j2 b/docs/account/_template/xias_need_sponsor.md.j2 new file mode 100644 index 000000000..f807482a2 --- /dev/null +++ b/docs/account/_template/xias_need_sponsor.md.j2 @@ -0,0 +1,3 @@ +!!! important + + All researchers creating and using XIAS accounts must have a UAB employed sponsor. diff --git a/docs/account/code.rc/_img/gitlab_researcher_ldap.png b/docs/account/code.rc/_img/gitlab_researcher_ldap.png new file mode 100644 index 000000000..d9b276e98 Binary files /dev/null and b/docs/account/code.rc/_img/gitlab_researcher_ldap.png differ diff --git a/docs/account/code.rc/_img/gitlab_researcher_standard.png b/docs/account/code.rc/_img/gitlab_researcher_standard.png new file mode 100644 index 000000000..9f95c5e1c Binary files /dev/null and b/docs/account/code.rc/_img/gitlab_researcher_standard.png differ diff --git a/docs/account/code.rc/create.md b/docs/account/code.rc/create.md new file mode 100644 index 000000000..77c839d67 --- /dev/null +++ b/docs/account/code.rc/create.md @@ -0,0 +1,74 @@ +--- +hide: + toc: true +--- + +# Create Your Code.rc (GitLab) Account + +**Code.rc** is an on-premises GitLab server running on UAB IT infrastructure, administered by Research Computing, and part of the Research Computing System (RCS). + +Creating a Code.rc account is an automated, self-service process for researchers affiliated with UAB. External collaborators follow a different process. + +## What Do I Need Before Starting? + +Before starting, you'll need the following prerequisites. + +- An [RCS Account](../rcs/index.md) in [Good Standing](../rcs/status.md#what-are-the-possible-statuses-good-standing-ok). + +## How Do I Create a Code.rc Account? + +Please select the tab that best described your affiliation to UAB to see instructions for creating a Code.rc account. + + +=== "UAB Campus & UAB Medicine" + + Please select the LDAP tab and authenticate with your BlazerID credentials. + + {% include "account/_template/uab_medicine_credentials.md.j2" indent content %} + + ![!screenshot of code.rc login pane with ldap tab selected](_img/gitlab_researcher_ldap.png) + +=== "External Collaborator (XIAS)" + + 1. Ensure that your sponsor has included `https://code.rc.uab.edu` in the list of [approved URIs](../xias/1_sponsor_manage_sites.md) on the XIAS Site configuration page. + + !!! important + + XIAS account researchers will only be granted access if their sponsor adds the Code.rc URI to the list of approved URIs. + + 1. Have your sponsor send a request to for a Code.rc account for their XIAS Guest. Please have the sponsor use the following template. + + ```text + I hereby request a Code.rc account created for a XIAS account, and affirm that the external collaborator has an RCS account in good standing. + + XIAS full name: _____ + XIAS email address: _____ + ``` + + 1. UAB Research Computing will create an account. + 1. You will receive an automated email from `donotreply.rc.code@uab.edu` with a link to create a password. + 1. Follow the link to create a password for your account. + 1. Navigate to to authenticate. + 1. Select the Standard tab and authenticate with your XIAS credentials. Only use the `name` portion of your XIAS email address `name@domain.tld`. Do not include the `@` symbol or anything after. Use the password you created in the previous steps. + + > Username or primary email: `name` + > + > Password: `********` + + ![!screenshot of code.rc login pane with standard tab selected](_img/gitlab_researcher_standard.png) + + 1. Click `Sign in` to authenticate. + +=== "Unaffiliated" + + {% include "account/_template/not_affiliated_with_uab.md.j2" indent content%} + + {% include "account/_template/xias_need_sponsor.md.j2" indent content %} + + +## Next Steps + +Now that your Code.rc (GitLab) account is created, learn more about how to use GitLab effectively. + +- [Official GitLab Tutorials](https://docs.gitlab.com/tutorials/) +- [Code.rc](../../code.rc/index.md) diff --git a/docs/account/code.rc/index.md b/docs/account/code.rc/index.md new file mode 100644 index 000000000..f50b16e6f --- /dev/null +++ b/docs/account/code.rc/index.md @@ -0,0 +1,26 @@ +--- +hide: + toc: true +--- + +# Create and Manage Code.rc (GitLab) Accounts + +UAB Research Computing maintains an on-premises GitLab server, part of the Research Computing System (RCS), called **Code.rc**. Generally speaking, [GitLab](https://about.gitlab.com/) is a service designed for collaborating on software development projects and is similar in structure and purpose to [GitHub](https://github.com/). In contrast to the Git hosting services [GitLab.com](https://gitlab.com) and [GitHub.com](https://github.com), Code.rc is hosted on-premises and stored in a secure physical environment on UAB Campus. + + +!!! important + + Code.rc accounts are managed separately from [Research Computing System (RCS) accounts](../rcs/index.md). Before creating a Code.rc account, you must create an RCS account. + + +{{ + renderer.render_cards( + cards.account.code_rc_create + ) +}} + +## Where Can I Find Code.rc? + +Code.rc may be found at . + +{% include "_template/base_help_section.md.j2" %} diff --git a/docs/account/code.rc/manage.md b/docs/account/code.rc/manage.md new file mode 100644 index 000000000..cf0dc9a7e --- /dev/null +++ b/docs/account/code.rc/manage.md @@ -0,0 +1,40 @@ +--- +hide: + toc: true +--- + +# Managing Code.rc (GitLab) Accounts + +You can manage your Code.rc (GitLab) account by navigating to the web interface at and checking your User Profile. Within Code.rc, you can create and manage Groups and Projects, including which other Users and Groups have access, and what level of access, by assigning Roles. + +## What Do I Need to Get Started? + +Before starting, you'll need the following prerequisites. + +- A [Code.rc Account](./index.md). + +## How Do I View User Profiles? + +To view a profile, including your own: + +- Visit `https://code.rc.uab.edu/your-username`. +- _or_ + 1. Login to . + 1. Click your profile picture at the top of the left-hand sidebar. On narrow displays, the sidebar may be hidden. If so, click the "Show Sidebar" icon at the top-left of any page. + 1. A pop-up menu will appear. + 1. Click your name at the top of the pop-up menu. + +## How Do I Edit My User Profile? + +To edit your profile: + +- Visit . +- _or_ [View Your Profile](#how-do-i-view-user-profiles), except instead of clicking your name at the last step, click "Edit Profile". + +## What Can Be Edited on My User Profile? + +You can change your profile picture, name, social media links, and bio in your user profile page. + +Please see the [Official GitLab Documentation](https://docs.gitlab.com/user/profile/) for more details. + +{% include "_template/base_help_section.md.j2" %} diff --git a/docs/account/index.md b/docs/account/index.md new file mode 100644 index 000000000..23ed7131e --- /dev/null +++ b/docs/account/index.md @@ -0,0 +1,19 @@ +--- +hide: + toc: true +--- + +# Account Creation and Management + +{{ + renderer.render_cards( + cards.account.rcs.create, + cards.account.rcs.status, + cards.account.responsibilities, + cards.account.leaving, + cards.account.xias_create, + cards.account.code_rc_create, + ) +}} + +{% include "_template/base_help_section.md.j2" %} diff --git a/docs/account/leaving/collaboration.md b/docs/account/leaving/collaboration.md new file mode 100644 index 000000000..19c305684 --- /dev/null +++ b/docs/account/leaving/collaboration.md @@ -0,0 +1,40 @@ +--- +hide: + toc: true +--- + +# Leaving UAB — Continuing Collaboration + +{% from "_macro/support.md.j2" import contact_support_link %} + +Because you intend to have a continuing collaboration after leaving UAB, you will need to transition from your current RCS account to a new one. + +Your current account is based on your BlazerID and will become inaccessible following the grace period. So, to continue operations, you will need to create a new RCS account based on a XIAS account. + +{% include "account/_template/xias_need_sponsor.md.j2" %} + +## What Is the XIAS Account Transition Procedure? + +1. Identify a UAB Sponsor for the XIAS account. This should be one of the UAB-affiliated collaborators you intend to work with. +1. Create the [XIAS Account](../xias/index.md). +1. Create a new [RCS Account](../rcs/create.md) +1. Please {{ contact_support_link() }} to request transfer of data from your previous BlazerID RCS account to your new XIAS RCS account. + + Please use the following template when sending the email. + + Your Sponsor must give approval for the transfer. + + ```text + RCS Former UAB Affiliate Account Transfer + + Please transfer my BlazerID RCS account data to my XIAS RCS account. + + - My former BlazerID: __ + - My new XIAS email address: __ + - What to transfer + - Cheaha storage individual allocation: YES/NO + - Long-Term Storage (LTS) individual allocation: YES/NO + - Cloud.rc (OpenStack) individual project: YES/NO + ``` + +{% include "account/xias/_template/xias_help_section.md.j2" %} diff --git a/docs/account/leaving/final_steps.md b/docs/account/leaving/final_steps.md new file mode 100644 index 000000000..2362d2754 --- /dev/null +++ b/docs/account/leaving/final_steps.md @@ -0,0 +1,50 @@ +# Leaving UAB — Final Steps + +{% from "_macro/support.md.j2" import contact_support_link %} + +All UAB students, staff, and faculty should make arrangements to properly manage their data as they prepare to leave UAB. + +## What Happens to Data in My Individual Storage Allocations? + +Data in your individual storage allocations, on all storage platforms, will be retained for the grace period. We recommend making a plan for your data. + +- Download any personal, non-UAB-owned data you want to keep. +- Make arrangements with your research faculty supervisor to transfer any UAB-owned research data to appropriate shared storage allocations. If you have multiple faculty supervisors, please work with each of them. + +## What Are My Responsibilities for Lab Shared Allocations? + +If you are responsible for lab shared allocations on Research Computing storage platforms, you have certain responsibilities for the data within them. Transferring UAB-owned data requires the involvement of the [Office of Research](https://www.uab.edu/research/home/about/contact-us), specifically the [Office of Sponsored Programs (OSP)](https://www.uab.edu/research/home/osp-about/contact). + +For each dataset or project, which option is ideal depends on the state of the project. + +- Transfer responsibility of the data to a successor (retiring)? + + 1. Make the appropriate arrangements with relevant administrative units (e.g., Office of Research and OSP). + 1. [Globus](../../data_management/transfer/globus.md) may be used to efficiently and robustly transfer the data from one directory on Cheaha to another. Please {{ contact_support_link() }} for more details. + +- Transfer the data to a new instutition (moving)? + + 1. Contact the Office of Research to create a "Data Use Agreement" with your new institution. Read more on the [OSP Site](https://www.uab.edu/research/home/osp-federal-contracts/fc-other/data-use-agreements). + 1. {{ contact_support_link() }} and your new institution's Research Computing equivalent to determine how to transfer data efficiently. + +- Comply with funding agency data retention regulations (retiring)? + + - Find a UAB-affiliated successor to manage the data for you in your absence. + - _OR_ Find an archival service suitable for long term data retention. + +- Something else? Please {{ contact_support_link() }}. + +## What Are My Responsibilities for Core Shared Allocations? + +Cores should not assume responsibility for any of the research data they produce or acquire. + +If the Core will continue operating, then it is assumed there will be a successor. Take whatever necessary administrative steps to transfer control and responsibility for Core operations. Things that may need to be transfered: + +- [GPFS (Cheaha) shared allocation](../../data_management/cheaha_storage_gpfs/project_directories.md). +- [LTS shared allocation](../../data_management/lts/index.md). +- [OpenStack Shared Projects](../../uab_cloud/sharing_cloud_environment.md). +- Service account, shared mailboxes, and other shared resources not managed by Research Computing, but which may have an impact on Core operations relating to Research Data acquisition and transfer, such as [Globus](../../data_management/transfer/globus.md). + +If the Core will cease operating, please {{ contact_support_link() }} to make arrangements to ensure final disposition of all research data. + +{% include "account/xias/_template/xias_help_section.md.j2" %} diff --git a/docs/account/leaving/index.md b/docs/account/leaving/index.md new file mode 100644 index 000000000..090548552 --- /dev/null +++ b/docs/account/leaving/index.md @@ -0,0 +1,69 @@ +# Leaving UAB + +{% from "_macro/support.md.j2" import contact_support_link %} + +If your life and career plans take you away from UAB, then this article is designed to help you. We hope to give you a better understanding of expectations and responsibilities for your account and data. + +All [research data](#what-is-research-data) produced as part of UAB research operations is owned by UAB. Funding agencies (e.g., NIH, NSF) often have strict data retention and sharing regulations. Transferring UAB-owned and/or agency funded data requires involvement of the [Office of Sponsored Programs (OSP)](https://www.uab.edu/research/home/osp-about/contact). + +If you have questions, concerns, or doubts after reading this page, we highly recommend you {{ contact_support_link() }}. + + +!!! note + + The contents of this article apply only to [research data](#what-is-research-data). For administrative and other data you will need to discuss with the UAB Administrative units appropriate to you and your situation. You can discuss with your faculty supervisor or contact for more information on what to do with other data. + + +## What Is Research Data? + +Research data acquired, analyzed, created, or produced as part of UAB research operations is property of UAB. + +## Why Is Research Data Important? + +All research data must be managed according to UAB, UAB IT, and funding agency policies and requirements. + +UAB research data may not leave UAB systems without a Data Use Agreement (DUA) signed by the [Office of Sponsored Programs (OSP)](https://www.uab.edu/research/home/osp-about/contact). + +## What Is the Grace Period? + +Researchers have a {{ account.leaving.grace_period_time }} grace period following the end of their relationship with UAB. + +Due to security requirements imposed by US federal funding agencies, we are unable to extend the grace period. + +## What Happens to My RCS Account? + +Your RCS account will be accessible for 30 days following the end of your relationship with UAB. + +The grace period is provided for you to finalize research data transfers. + +The same grace period applies to all other Research Computing platform accounts. + +If you anticipate needing more than 30 days to finalize transfers, {{ contact_support_link() }} as soon as possible so we can make arrangements or work to improve data transfer efficiency. + +## What Are My Next Steps? + +For more information on what to do next, please select the tab below that most closely matches your situation. + + +=== "I Need Continuing Access" + + If you need RCS access beyond the end of the {{ account.leaving.grace_period_time }} grace period, you will need to create a [XIAS Account](../xias/index.md). + + {% include "account/_template/xias_need_sponsor.md.j2" indent content %} + + Please see [Continuing Collaboration](collaboration.md) + +=== "I Will Be Hired in a New Role" + + - **New role doesn't require RCS access?** Please select the "I No Longer Need Access" tab for next steps. + - **Hire date within grace period?** No action required, expect continuous access. + - **Hire date after grace period ends?** Please {{ contact_support_link() }}. + +=== "I No Longer Need Access" + + If the {{ account.leaving.grace_period_time }} grace period is enough time, then please be aware there are expectations and responsibilities for final handling of your research data. + + Please see [Final Steps For Research Data](final_steps.md) + + +{% include "account/xias/_template/xias_help_section.md.j2" %} diff --git a/docs/account/rcs/_img/rcs-create-account-form.png b/docs/account/rcs/_img/rcs-create-account-form.png new file mode 100644 index 000000000..cf8882f75 Binary files /dev/null and b/docs/account/rcs/_img/rcs-create-account-form.png differ diff --git a/docs/account/rcs/_img/rcs-create-account-wait.png b/docs/account/rcs/_img/rcs-create-account-wait.png new file mode 100644 index 000000000..c5201a894 Binary files /dev/null and b/docs/account/rcs/_img/rcs-create-account-wait.png differ diff --git a/docs/account/rcs/_img/rcs-status-page-certify-form.png b/docs/account/rcs/_img/rcs-status-page-certify-form.png new file mode 100644 index 000000000..e5786821e Binary files /dev/null and b/docs/account/rcs/_img/rcs-status-page-certify-form.png differ diff --git a/docs/account/rcs/_img/rcs-status-page-good-standing-ok.png b/docs/account/rcs/_img/rcs-status-page-good-standing-ok.png new file mode 100644 index 000000000..679e0f4f1 Binary files /dev/null and b/docs/account/rcs/_img/rcs-status-page-good-standing-ok.png differ diff --git a/docs/account/rcs/_img/rcs-status-page-hold.png b/docs/account/rcs/_img/rcs-status-page-hold.png new file mode 100644 index 000000000..8a5c80e48 Binary files /dev/null and b/docs/account/rcs/_img/rcs-status-page-hold.png differ diff --git a/docs/account/rcs/_img/rcs-status-page-pre-and-certification.png b/docs/account/rcs/_img/rcs-status-page-pre-and-certification.png new file mode 100644 index 000000000..a40d47541 Binary files /dev/null and b/docs/account/rcs/_img/rcs-status-page-pre-and-certification.png differ diff --git a/docs/account/rcs/_res/status_summary.csv b/docs/account/rcs/_res/status_summary.csv new file mode 100644 index 000000000..1c79c8d4d --- /dev/null +++ b/docs/account/rcs/_res/status_summary.csv @@ -0,0 +1,5 @@ +Status,RCS Service Access,Action Required to Restore Service +[Good Standing (OK)](#what-are-the-possible-statuses-good-standing-ok),Yes ✔️, +[Pre-Certification](#what-are-the-possible-statuses-pre-certification),Yes ✔️,[Recommended 🔘](#how-do-i-certify-my-account) +[Certification](#what-are-the-possible-statuses-certification),No ❌,[Required ⚠️](#how-do-i-certify-my-account) +[On Hold](#what-are-the-possible-statuses-hold),No ❌,[Required ⚠️](#how-do-i-restore-my-on-hold-account) diff --git a/docs/account/rcs/create.md b/docs/account/rcs/create.md new file mode 100644 index 000000000..f3ef0aa89 --- /dev/null +++ b/docs/account/rcs/create.md @@ -0,0 +1,144 @@ +--- +hide: + toc: true +--- + +# Create Your Research Computing Systems (RCS) Account + +Creating an RCS account is an automated, self-service process for UAB-affiliated researchers. External collaborators will need to follow a different process. + +## What Do I Need Before Starting? + +Before starting, you'll need to meet one of the following prerequisites. + +- Have one of the following affiliations to UAB Campus: faculty, staff, student; +- _or_ be employed by UAB Medicine; +- _or_ have a XIAS account with a UAB-affiliated Sponsor. + +Additionally, you must meet the following prerequisite. + +- Your work on RCS must be research or in direct support of research. + + +!!! security + + Direct patient care operations are not permitted on RCS. Please reach out to IT or IS contacts within your department for advice on how to proceed. + + +## How Do I Create an RCS Account? + +To create your account, use your browser to navigate to our web interface at . + +You will be asked to login using Single Sign-on (SSO). Please select the tab that best describes your affiliation to UAB to see login instructions. + + +=== "UAB Campus & UAB Medicine" + + Please login with your BlazerID credentials. + + {% include "account/_template/uab_medicine_credentials.md.j2" indent content %} + +=== "External Collaborator (XIAS)" + + {% include "account/_template/first_time_2fa.md.j2" indent content %} + + Please login with your XIAS account credentials. In the "BlazerID" box, put the email you used to register for your XIAS account. In the "Password" box, enter the password you configured when creating your XIAS account. + + > BlazerID: `name@domain.tld` + > + > Password: `********` + +=== "Unaffiliated" + + {% include "account/_template/not_affiliated_with_uab.md.j2" indent content %} + + {% include "account/_template/xias_need_sponsor.md.j2" indent content %} + + +When you have authenticated you will be automatically taken to a form to create your account. Please select the tab that best describes your affiliation to UAB to see form instructions. If you wish to stop, click the "Cancel" button at the bottom of the form, or close your browser. + + +=== "UAB Campus & UAB Medicine" + + The form should be prefilled with your BlazerID, Full Name, and UAB Campus email address. Please verify the details are correct. + + See incorrect or missing information? Please [Contact Support](../../help/support.md). + + ![!UAB self registration page.](_img/rcs-create-account-form.png) + +=== "External Collaborator (XIAS)" + + The form should be prefilled as shown below. Only use the `name` portion of your XIAS email address `name@domain.tld` in the BlazerID field. Use your full XIAS email address in the Email field. + + > BlazerID: `name` + > + > Full Name: firstname lastname + > + > Email: `name@domain.tld` + + ![!UAB self registration page.](_img/rcs-create-account-form.png) + +=== "Unaffiliated" + + {% include "account/_template/not_affiliated_with_uab.md.j2" indent content %} + + {% include "account/_template/xias_need_sponsor.md.j2" indent content %} + + +Please fill out the reason you wish to create an account in the form. It would be helpful to include information about your research use cases, needs, and how you believe RCS will help you. + +You must read and agree to all relevant UAB IT policies. If you agree, please check the checkboxes. + +When the form is completed, the "Create Account" button will become active. When you are ready, click the "Create Account" button to create your account. When you click this button, it will not be possible to stop the account creation process using the "Cancel" button. + +After clicking the "Create Account" button, you should see a popup notification indicating that your account is being created. The process should take no longer than five minutes. + +![!Account creation notification popup](_img/rcs-create-account-wait.png) + +When the process is complete, you will be redirected to our [Open OnDemand](../../cheaha/open_ondemand/index.md) web interface. + +Welcome to Cheaha and to Research Computing! + +## Next Steps + +Please take some time to familiarize yourself with responsibilities, expectations, and policies around use of RCS. + +{{ + renderer.render_cards( + cards.account.responsibilities + ) +}} + +Research Computing has many services available to RCS account holders. To learn more about services that may interest you, please select the role that most closely matches yours. + + +=== "Student | Staff | XIAS Guest" + + {{ + renderer.render_cards( + cards.platforms.cheaha.ood.overview, + cards.platforms.cheaha.slurm.overview, + cards.data.individual_storage, + cards.data.transfer_options, + cards.education.training, + cards.education.dsjc, + cards.account.code_rc_create, + ) | indent(4) + }} + +=== "Research Faculty Supervisor | Core Director" + + {{ + renderer.render_cards( + cards.platforms.cheaha.ood.overview, + cards.platforms.cheaha.slurm.overview, + cards.data.shared_storage, + cards.data.transfer_options, + cards.platforms.cloud_rc.overview, + cards.platforms.cloud_rc.web_server, + cards.account.code_rc_create, + ) + }} | indent(4) + + +{% include "_template/base_help_section.md.j2" %} diff --git a/docs/account/rcs/index.md b/docs/account/rcs/index.md new file mode 100644 index 000000000..2b3a1126d --- /dev/null +++ b/docs/account/rcs/index.md @@ -0,0 +1,14 @@ +--- +hide: + toc: true +--- + +# Create and Manage Research Computing System (RCS) Accounts + +{{ + renderer.render_namespace( + cards.account.rcs + ) +}} + +{% include "_template/base_help_section.md.j2" %} diff --git a/docs/account/rcs/status.md b/docs/account/rcs/status.md new file mode 100644 index 000000000..57a3eae66 --- /dev/null +++ b/docs/account/rcs/status.md @@ -0,0 +1,125 @@ +# Research Computing System (RCS) Account Status + +All Research Computing System (RCS) accounts have a status. Statuses determine whether an account may access RCS services, and what actions may be required to restore access. + +The following table has more information on each status, with links for more details. To check your status see [How Do I Check My RCS Account Status?](#how-do-i-check-my-rcs-account-status) + +{{ read_csv("_res/status_summary.csv", keep_default_na=False) }} + +## What Are the Possible Statuses? + + +=== "Good Standing (OK)" + + When an account is in Good Standing (OK) status, all RCS services are accessible and no action is required. + + While in Good Standing (OK) status, The [Account Status page](#how-do-i-check-my-rcs-account-status) will show "Account in Good Standing", as shown below. + + ![!screenshot showing good standing page](_img/rcs-status-page-good-standing-ok.png) + +=== "Pre-Certification" + + When an account is in Pre-Certification status, all RCS services are accessible and action will be required soon. + + ?? days after entering Pre-Certification status, accounts will enter Certification status and action will be required. To prevent Certification status, you may certify at any time. + + While in Pre-Certification status, the [Account Status page](#how-do-i-check-my-rcs-account-status) will show "Account in Pre-Certification", as shown below. + + ![!screenshot showing pre-certification page](_img/rcs-status-page-pre-and-certification.png) + + - [How Do I Certify My Account?](#how-do-i-certify-my-account) + - [Why Is Certification Required?](#why-is-certification-required) + +=== "Certification" + + When an account is in Certification status, all RCS services become inaccessible and action is required to restore access. + + ?? days after entering Certification status, accounts will enter Hold status. To prevent Hold status, complete the certification process. + + While in Certification status, the [Account Status page](#how-do-i-check-my-rcs-account-status) will show "Account requires Certification". + + ![!screenshot showing account certification page](_img/rcs-status-page-pre-and-certification.png) + + - [How Do I Certify My Account?](#how-do-i-certify-my-account) + - [Why Is My Account in Certification Status?](#why-is-my-account-in-certification-status) + - [Why Is Certification Required?](#why-is-certification-required) + +=== "Hold" + + When an account is in Hold status, all RCS services become inaccessible and action is required to restore the account. + + While in Hold status, the [Account Status page](#how-do-i-check-my-rcs-account-status) will show "Account on Hold". + + ![!screenshot of account hold page](_img/rcs-status-page-hold.png) + + SSH connections are refused. Attempting to connect will display text like following, followed by disconnection. + + ```text + Your account has expired; please contact your system administrator. + account expired 2 days ago. + ``` + + If an account in Hold status is restored, it will be put in Certification status. + + - [Why Is My Account on Hold?](#why-is-my-account-on-hold) + - [How Do I Restore My on Hold Account?](#how-do-i-restore-my-on-hold-account) + + +## How Do I Check My RCS Account Status? + +To check your RCS account status, navigate to our web interface at using your browser and log in as usual. When logged in, you should see a short page reflecting your current account status. + +## How Do I Certify My Account? + +To certify your account, click the button to be taken to the certification form, which should look like the following. Carefully review the information in the form and, when ready, click "Certify Account" to certify. You should see a popup notification confirming the process is working. After a few moments your account should be certified and returned to Good Standing (OK) status. + +![!screenshot showing account certification form](_img/rcs-status-page-certify-form.png) + +See [Certification Status :octicons-arrow-right-24:](#what-are-the-possible-statuses-certification) + +## Why Is Certification Required? + +Research Computing periodically reviews accounts to enhance system security and ensure compliance with [expectations, responsibilities, and policies](../responsibilities.md). Part of the review process is confirming each researcher intends to continue using RCS services, accomplished through a certification form. + +The account certification process allows us to ensure RCS resources are associated only with active accounts and enable us to identify and retire inactive and unaffiliated accounts. These actions help us to enhance security and ensure resources are allocated fairly. + +See [Certification Status :octicons-arrow-right-24:](#what-are-the-possible-statuses-certification) + +## Why Is My Account in Certification Status? + +Accounts may be put into Certification status when: + +- one calendar year has passed since account creation or the last certification; +- inactive for ?? days; +- restored from [Hold status](#what-are-the-possible-statuses-hold). + +See [Certification Status :octicons-arrow-right-24:](#what-are-the-possible-statuses-certification) + +## Why Is My Account on Hold? + +There are multiple reasons an account can be put on hold. + +- Required for RCS maintenance. +- Extended account inactivity. +- Loss of RCS authorization. +- Non-compliance with: + - IT policy; + - UAB policy; + - security requirements; + - regulatory and legal requirements; + - funding agency agreements; + - software license, terms, contracts, and agreements; + - data license, terms, contracts, and agreements. +- Unfair use or misuse of RCS services. +- When required for investigation. +- In emergencies to prevent unrecoverable loss of data. + +See [Hold Status :octicons-arrow-right-24:](#what-are-the-possible-statuses-hold) + +## How Do I Restore My on Hold Account? + +To discuss restoration of an account in Hold status, please [Contact Support](../../help/support.md). + +See [Hold Status :octicons-arrow-right-24:](#what-are-the-possible-statuses-hold) + +{% include "_template/base_help_section.md.j2" %} diff --git a/docs/account/responsibilities.md b/docs/account/responsibilities.md new file mode 100644 index 000000000..ca79aa8ca --- /dev/null +++ b/docs/account/responsibilities.md @@ -0,0 +1,34 @@ +--- +hide: + toc: true +--- + +# Responsibilities, Expectations, and Policies + +{% from "_macro/support.md.j2" import contact_support_link %} + +where responsible and professional use of Cheaha accounts, storage, and computational resources is expected to maintain system integrity and support collaborative research. Please refer below for the eligibility requirements and responsibilities of Research Computing services users. + + +=== "Student, Staff, XIAS Guest" + + {% include "account/_template/responsibilities_for_all.md.j2" indent content %} + +=== "Research Faculty Supervisor" + + {% include "account/_template/responsibilities_for_all.md.j2" indent content %} + {% include "account/_template/responsibilities_security.md.j2" indent content %} + - Responsible and accountable for all [XIAS Guest](xias/index.md) actions and behavior. + - Research data lifecycle management + - Migrate unused data to [LTS](../data_management/lts/index.md) or archive. + - Backup critical data. + - {{ contact_support_link() }} to discuss. + +=== "Core Director" + + {% include "account/_template/responsibilities_for_all.md.j2" indent content %} + {% include "account/_template/responsibilities_security.md.j2" indent content %} + - Responsible and accountable for all [XIAS Guest](xias/index.md) actions and behavior. + - Research data lifecycle management + - {{ contact_support_link() }} to discuss data management plans leveraging no-cost Research Computing resources. + diff --git a/docs/account/xias/1_sponsor_manage_sites.md b/docs/account/xias/1_sponsor_manage_sites.md new file mode 100644 index 000000000..954bd9535 --- /dev/null +++ b/docs/account/xias/1_sponsor_manage_sites.md @@ -0,0 +1,81 @@ +# Sponsor — Creating and Managing XIAS Sites + +{% include "_template/uab_employee_use_only.md.j2" %} + +{% include "account/xias/_template/sponsor_responsibility.md.j2" %} + +XIAS Sites tie external collaborators to specific technology resources at UAB through uniform resource identifiers (URIs). Connecting people to the resources they use enables UAB to maintain security and accountability. + +## What Do I Need Before Starting? + +Before starting, you'll need the following prerequisites. + +- An [RCS Account](../rcs/index.md). +- A list of RCS resources each Guest needs access to. + +## Where Will I Be Working? + +- [XIAS Manage Projects/Sites page](https://idm.uab.edu/cgi-cas/xrmi/sites) + +## How Do I Create a XIAS Site? + +Creating a Site is the first phase of sponsoring access for external collaborators. Sites are reusable, and can be configured one time and used for multiple Guests. You can also make one site for each individual resource, and assign each Guest to multiple sites, giving you more flexibility over assignment. + +1. Login to the [XIAS Manage Projects/Sites page](https://idm.uab.edu/cgi-cas/xrmi/sites). + + ![!Screenshot of XIAS Manage Project/Site page with Project/Site table.](_img/xias_sites_add_000.png) + +1. Click New to open a form for creating a new Project/Site. + + ![!Screenshot of blank XIAS Project/Site creation form.](_img/xias_sites_add_001.png) + +1. Fill in the form. All fields are required. + + 1. **Short name for project/site**: (Required) A compact, memorable name for your Site. + 1. **Longer description**: (Required) A complete, concise description of the Site and its resources. + 1. **Start date**: (Required) The start date of the Site. Can be today. + 1. **End date**: (Required) An expiration date for the Site. + + + !!! warning + + XIAS accounts associated with this Site may lose access to resources after the end date. + + + 1. **URIs**: (Required) One or more uniform resource identifiers (URIs) associated with the Site. + + Resource identifiers associated with RCS resources. + + {{ read_csv("account/xias/_res/rcs_uri.csv") }} + + + !!! tip + + If you aren't sure which URI to use for an RCS resource, please [Contact Support](../../help/support.md). + + For other UAB resources, please contact . + + + Below is an example of a filled in form. + + ![!Screenshot of filled XIAS Site creation form.](_img/xias_sites_add_002.png) + +1. Click Add to submit the form. You should be taken to a page summarizing the created Project/Site. + + ![!Screenshot of summary page after creating Site.](_img/xias_sites_add_003.png) + +### Next Steps + +To continue creating a XIAS account, move to [2. Sponsor — Manage Users](./2_sponsor_manage_users.md). + +## How Do I Manage a XIAS Site? + +Login to the [XIAS Manage Projects/Sites page](https://idm.uab.edu/cgi-cas/xrmi/sites). You will see a table of existing Sites. + +![!Screenshot of site table with one site listed.](_img/xias_sites_add_004.png) + +- To view a Site, click the View button next to the desired Site. You will see a read-only view of the Site's configuration. +- To edit a Site, click the Edit button next to the desired Site. You will be able to change Sites steps created in [Creating a XIAS Site](#how-do-i-create-a-xias-site). +- Click the User button to be taken to the Manage Users page. The page will show a table of Users associated with the selected Site. See [How Do I Manage a Xias User](./2_sponsor_manage_users.md#how-do-i-manage-a-xias-user). + +{% include "account/xias/_template/xias_help_section.md.j2" %} diff --git a/docs/account/xias/2_sponsor_manage_users.md b/docs/account/xias/2_sponsor_manage_users.md new file mode 100644 index 000000000..285ce48ef --- /dev/null +++ b/docs/account/xias/2_sponsor_manage_users.md @@ -0,0 +1,98 @@ +# Sponsor — Creating and Managing XIAS Users + +{% include "_template/uab_employee_use_only.md.j2" %} + +{% include "account/xias/_template/sponsor_responsibility.md.j2" %} + +XIAS Users tie external collaborators to UAB's Identity Management (IDM) system. Creating a XIAS User means an external collaborator will be able to use Single Sign-on (SSO) to login to UAB technology resources. + +## What Do I Need Before Starting? + +Before starting, you'll need the following prerequisites. + +- A [Research Computing System (RCS) Account](../rcs/index.md). +- At least one configured [XIAS Site](./1_sponsor_manage_sites.md). +- The email address each Guest wants to register with. + +## Where Will I Be Working? + +- [XIAS "Manage Users" page](https://idm.uab.edu/cgi-cas/xrmi/users) + +## How Do I Create a XIAS User? + +Creating a User is the second phase of sponsoring access for external collaborators. Each User may be assigned to multiple Sites, but at least one Site must exist to create a User. + +1. Login to the [XIAS "Manage Users" page](https://idm.uab.edu/cgi-cas/xrmi/users). + + ![!Screenshot of XIAS Manage Users page with Select Project/Site selector and User search field.](_img/xias_users_add_000.png) + +1. In the Select Project/Site drop down menu, select the Site you want to add Users to. + + ![!Screenshot of Select Project/Site drop down menu with a Site highlighted by mouse cursor.](_img/xias_users_add_001.png) + +1. Click Register. You should be taken to a form. + + ![!Screenshot of default User registration form.](_img/xias_users_add_002.png) + +1. Fill in the form. The Site you selected in the previous step should be listed with a checked checkbox. + + 1. **Site Checkboxes**: (Required) Leave the Site you selected checked. You may check additional Sites if appropriate. At least one Site must be checked. + 1. **End date** (Required) An expiration date for the User's association to the Site. Can be today. Cannot be later than the Site's end date. + 1. **Text box** (Required) Enter a list of email addresses of Users to add to the Site. One email address per line. + + ![!Screenshot of fill User registration form.](_img/xias_users_add_003.png) + +1. Click Submit. You should be taken to a page requesting your confirmation the email addresses you entered are correct. + + ![!Screenshot of page requesting email confirmation.](_img/xias_users_add_004.png) + +1. If the email addresses are not correct, make any necessary corrections. +1. When you are satisfied, click Add. Emails will be automatically sent by the XIAS system to all added email addresses. You should be taken to the XIAS User Management Webpage. You should see the text "Registration successful" near the top of the page. + + ![!Screenshot of XIAS Manage Users page with the text Registration successful.](_img/xias_users_add_005.png) + +## Next Steps + +The next steps will be done by the XIAS Users you've created. Please direct them to [3. Guest — Create XIAS Account](./3_guest_create_xias_account.md). + +When they have completed account creation, you should receive an email from `UserServices@uab.edu` like the following. + +![!Screenshot of email sent to Sponsor following guest creation of XIAS account.](_img/xias_users_add_006.png) + +## How Do I Manage a XIAS User? + +{% include "account/xias/_template/revoke_access.md.j2" %} + + +!!! info + + There is currently no way to remove a User from a Site using the XIAS Manage Users page. Instead update their end date to a date after the start date and before today. + + If you must remove the user completely, please contact . + + +Login to the [XIAS "Manage Users" page](https://idm.uab.edu/cgi-cas/xrmi/users). + +![!Screenshot of XIAS Manage Users page with Select Project/Site selector and User search field.](_img/xias_users_add_000.png) + +### How Do I Update User End Dates? + +1. In the Select Project/Site drop down menu, select the Site whose users you want to View. + + ![!Screenshot of Select Project/Site drop down menu with a Site highlighted by mouse cursor.](_img/xias_users_add_001.png) + +1. Click List. The page should update. You should see a table of Users at the top of the page. + + ![!Screenshot of Site User table.](_img/xias_users_manage_001.png) + +1. Enter a new end date into the "Change end date for selected users to" field. +1. Check the checkboxes in the rows of Users whose end dates you want to update. +1. Click Update. The page should update. You should see the new end dates shown immediately. + + +!!! tip + + You can also search for Users by email address using the "Locate specific user(s) by e-mail address" field. + + +{% include "account/xias/_template/xias_help_section.md.j2" %} diff --git a/docs/account/xias/3_guest_create_xias_account.md b/docs/account/xias/3_guest_create_xias_account.md new file mode 100644 index 000000000..4645c10ae --- /dev/null +++ b/docs/account/xias/3_guest_create_xias_account.md @@ -0,0 +1,118 @@ +# Guest - Creating a XIAS Account + +These instructions are for guests who have been registered by UAB faculty and staff to use internal UAB resources. Once a request for a XIAS account has been made by your UAB sponsor, you will need to follow these instructions to complete the XIAS registration and obtain access to UAB resources. All of the links used on this page are available at the [UAB XIAS Guest Users](https://apps.idm.uab.edu/xias/top) page. + +## What Do I Need Before Starting? + +Before starting, you'll need the following prerequisites. + +- A XIAS Sponsor who has completed the [Sponsor phases](./index.md) of XIAS account creation. +- Access to the email address you gave your Sponsor. + +## How Do I Create a XIAS Account? + +1. After your Sponsor completes their phases, you should receive an email from `UserServices@uab.edu` that looks like the following. + + ![!Screenshot of first email.](_img/xias_guest_001.png) + + + ??? note "Email Contents" + + > Subject: UAB online resource access + > + > From: UAB Identity Management `` + > + > A request has been received to grant you access to the following inline resource(s) at the University of Alabama at Birmingham (UAB): + > + > List of XIAS Sites + > + > Since you are not a UAB employee or student, you will not have a BlazerID, which is the usual identifier for accessing UAB online resources. Instead, special credentials will be set up for you through UAB's External ID Access Support (XIAS). You should receive a separate e-mail later today with instructions for creating the XIAS password. + > + > If you have any questions, do not hesitate to contact us via the AskIT Helpdesk at 205-996-5555 or e-mail `AskIT@uab.edu`. + + +1. You should receive a second email from `UserServices@uab.edu` that looks like the following. + + ![!Screenshot of second email.](_img/xias_guest_002.png) + + + ??? note "Email Contents" + + > Subject: UAB External ID (XIAS) registration + > + > From: UAB Identity Management `` + > + > At the request of a University of Alabama at Birmingham (UAB) department, you have been authorized as an external user to access one or more UAB online resources. + > + > To log in to these resources, you will need to register an External ID Access (XIAS) account. Please follow these instructions to complete the setup of your account. + > + > 1. Go to `https://idm.uab.edu/xias` + > 1. Click on the link for "Enter Invite or Reset Code". + > 1. On the form, submit your e-mail address (`name@domain.tld`) and the code: + > + > `code here` + > + > 1. Provide the requested information on the screens which follow. + > + > This code will expire in 72 hours. You must complete your registration before then, or a new code will have to be requested. + > + > The person or department who sponsored your access should provide you with separate instructions for accessing the resource(s). Note that since this is a new account, it may take some time for your access to be fully established after the registration is completed. + > + > If you have any questions or encounter any difficulties with this process, please contact the AskIT Help Desk at 205.996.5555 or `AskIT@uab.edu`. + + + + !!! danger + + Never click links in emails! Phishing emails target people who click links in emails. Read more about [UAB IT Security Awareness](https://www.uab.edu/it/home/security/awareness). + + + If you did not receive this email, or are missing the code, please visit and click "Resend Invite Code". If this still does not work, please contact for assistance. + +1. Use your browser to navigate to the link in the email, or click the following link . You should see a page that looks like the following. + + ![!Screenshot of XIAS Guest Users page.](_img/xias_guest_003.png) + +1. Click the "Enter Invite or Reset Code" link in the left-hand navigation menu. You will be taken to the "Register XIAS Account" page. + + Enter the email address you gave to your Sponsor to create this account in the "E-mail address" field. Enter the code from the second email in the "Invite (or reset) code" field. + + ![!Screenshot of Invite or Reset Code form with email and code entry fields.](_img/xias_guest_004.png) + +1. Click Proceed. You will be taken to a second form. Enter your first name (given name) and last name (surname). + + ![!Screenshot of form with name entry fields.](_img/xias_guest_006.png) + +1. Click Proceed. You will be taken to a third, final form. Enter a password according to the requirements shown on the page. + + ![!Screenshot of form with password fields.](_img/xias_guest_007.png) + +1. Click Proceed. You will be taken to a confirmation page. If you are not satisfied, click the Edit buttons to change the information. + + ![!Screenshot of confirmation page.](_img/xias_guest_008.png) + +1. When you are satisfied, click Proceed. You should be taken to a success page. Please read the page and follow any instructions. + + ![!Registration success page with additional instructions and suggestions.](_img/xias_guest_009.png). + +## Next Steps + +From here, you may create an [RCS Account](../rcs/index.md). + +All RCS services require two-factor authentication (2FA) and some require UAB Campus Network VPN access. + +{% include "account/_template/first_time_2fa.md.j2" %} + +{% include "account/_template/first_time_vpn.md.j2" %} + +## How Do I Manage My XIAS Account? + +To manage your XIAS account, visit the [XIAS Guest Users page](https://apps.idm.uab.edu/xias/top). You can take the following actions to manage your XIAS account. + + +!!! important + + XIAS accounts are different from RCS accounts. Managing one does not change the other. + + +{% include "_template/base_help_section.md.j2" %} diff --git a/docs/account_management/xias/images/xias_guest_001.png b/docs/account/xias/_img/xias_guest_001.png similarity index 100% rename from docs/account_management/xias/images/xias_guest_001.png rename to docs/account/xias/_img/xias_guest_001.png diff --git a/docs/account_management/xias/images/xias_guest_002.png b/docs/account/xias/_img/xias_guest_002.png similarity index 100% rename from docs/account_management/xias/images/xias_guest_002.png rename to docs/account/xias/_img/xias_guest_002.png diff --git a/docs/account/xias/_img/xias_guest_003.png b/docs/account/xias/_img/xias_guest_003.png new file mode 100644 index 000000000..f04cea11e Binary files /dev/null and b/docs/account/xias/_img/xias_guest_003.png differ diff --git a/docs/account/xias/_img/xias_guest_004.png b/docs/account/xias/_img/xias_guest_004.png new file mode 100644 index 000000000..00fb56820 Binary files /dev/null and b/docs/account/xias/_img/xias_guest_004.png differ diff --git a/docs/account_management/xias/images/xias_guest_006.png b/docs/account/xias/_img/xias_guest_006.png similarity index 100% rename from docs/account_management/xias/images/xias_guest_006.png rename to docs/account/xias/_img/xias_guest_006.png diff --git a/docs/account/xias/_img/xias_guest_007.png b/docs/account/xias/_img/xias_guest_007.png new file mode 100644 index 000000000..7f19f58ee Binary files /dev/null and b/docs/account/xias/_img/xias_guest_007.png differ diff --git a/docs/account/xias/_img/xias_guest_008.png b/docs/account/xias/_img/xias_guest_008.png new file mode 100644 index 000000000..d94b9b160 Binary files /dev/null and b/docs/account/xias/_img/xias_guest_008.png differ diff --git a/docs/account_management/xias/images/xias_guest_009.png b/docs/account/xias/_img/xias_guest_009.png similarity index 100% rename from docs/account_management/xias/images/xias_guest_009.png rename to docs/account/xias/_img/xias_guest_009.png diff --git a/docs/account_management/xias/images/xias_guest_activate_accounts.png b/docs/account/xias/_img/xias_guest_activate_accounts.png similarity index 100% rename from docs/account_management/xias/images/xias_guest_activate_accounts.png rename to docs/account/xias/_img/xias_guest_activate_accounts.png diff --git a/docs/account_management/xias/images/xias_guest_change_password.png b/docs/account/xias/_img/xias_guest_change_password.png similarity index 100% rename from docs/account_management/xias/images/xias_guest_change_password.png rename to docs/account/xias/_img/xias_guest_change_password.png diff --git a/docs/account_management/xias/images/xias_guest_it_info.png b/docs/account/xias/_img/xias_guest_it_info.png similarity index 100% rename from docs/account_management/xias/images/xias_guest_it_info.png rename to docs/account/xias/_img/xias_guest_it_info.png diff --git a/docs/account_management/xias/images/xias_guest_resend.png b/docs/account/xias/_img/xias_guest_resend.png similarity index 100% rename from docs/account_management/xias/images/xias_guest_resend.png rename to docs/account/xias/_img/xias_guest_resend.png diff --git a/docs/account_management/xias/images/xias_sites_add_000.png b/docs/account/xias/_img/xias_sites_add_000.png similarity index 100% rename from docs/account_management/xias/images/xias_sites_add_000.png rename to docs/account/xias/_img/xias_sites_add_000.png diff --git a/docs/account_management/xias/images/xias_sites_add_001.png b/docs/account/xias/_img/xias_sites_add_001.png similarity index 100% rename from docs/account_management/xias/images/xias_sites_add_001.png rename to docs/account/xias/_img/xias_sites_add_001.png diff --git a/docs/account_management/xias/images/xias_sites_add_002.png b/docs/account/xias/_img/xias_sites_add_002.png similarity index 100% rename from docs/account_management/xias/images/xias_sites_add_002.png rename to docs/account/xias/_img/xias_sites_add_002.png diff --git a/docs/account_management/xias/images/xias_sites_add_003.png b/docs/account/xias/_img/xias_sites_add_003.png similarity index 100% rename from docs/account_management/xias/images/xias_sites_add_003.png rename to docs/account/xias/_img/xias_sites_add_003.png diff --git a/docs/account_management/xias/images/xias_sites_add_004.png b/docs/account/xias/_img/xias_sites_add_004.png similarity index 100% rename from docs/account_management/xias/images/xias_sites_add_004.png rename to docs/account/xias/_img/xias_sites_add_004.png diff --git a/docs/account/xias/_img/xias_users_add_000.png b/docs/account/xias/_img/xias_users_add_000.png new file mode 100644 index 000000000..bea5f6570 Binary files /dev/null and b/docs/account/xias/_img/xias_users_add_000.png differ diff --git a/docs/account_management/xias/images/xias_users_add_001.png b/docs/account/xias/_img/xias_users_add_001.png similarity index 100% rename from docs/account_management/xias/images/xias_users_add_001.png rename to docs/account/xias/_img/xias_users_add_001.png diff --git a/docs/account_management/xias/images/xias_users_add_002.png b/docs/account/xias/_img/xias_users_add_002.png similarity index 100% rename from docs/account_management/xias/images/xias_users_add_002.png rename to docs/account/xias/_img/xias_users_add_002.png diff --git a/docs/account_management/xias/images/xias_users_add_003.png b/docs/account/xias/_img/xias_users_add_003.png similarity index 100% rename from docs/account_management/xias/images/xias_users_add_003.png rename to docs/account/xias/_img/xias_users_add_003.png diff --git a/docs/account_management/xias/images/xias_users_add_004.png b/docs/account/xias/_img/xias_users_add_004.png similarity index 100% rename from docs/account_management/xias/images/xias_users_add_004.png rename to docs/account/xias/_img/xias_users_add_004.png diff --git a/docs/account_management/xias/images/xias_users_add_005.png b/docs/account/xias/_img/xias_users_add_005.png similarity index 100% rename from docs/account_management/xias/images/xias_users_add_005.png rename to docs/account/xias/_img/xias_users_add_005.png diff --git a/docs/account_management/xias/images/xias_users_add_006.png b/docs/account/xias/_img/xias_users_add_006.png similarity index 100% rename from docs/account_management/xias/images/xias_users_add_006.png rename to docs/account/xias/_img/xias_users_add_006.png diff --git a/docs/account_management/xias/images/xias_users_list_000.png b/docs/account/xias/_img/xias_users_list_000.png similarity index 100% rename from docs/account_management/xias/images/xias_users_list_000.png rename to docs/account/xias/_img/xias_users_list_000.png diff --git a/docs/account_management/xias/images/xias_users_list_001.png b/docs/account/xias/_img/xias_users_list_001.png similarity index 100% rename from docs/account_management/xias/images/xias_users_list_001.png rename to docs/account/xias/_img/xias_users_list_001.png diff --git a/docs/account/xias/_img/xias_users_manage_001.png b/docs/account/xias/_img/xias_users_manage_001.png new file mode 100644 index 000000000..e6a508007 Binary files /dev/null and b/docs/account/xias/_img/xias_users_manage_001.png differ diff --git a/docs/account/xias/_res/rcs_uri.csv b/docs/account/xias/_res/rcs_uri.csv new file mode 100644 index 000000000..249847d21 --- /dev/null +++ b/docs/account/xias/_res/rcs_uri.csv @@ -0,0 +1,5 @@ +RCS Resource,Uniform Resource Identifier (URI) +Cheaha (HPC Cluster),`https://cheaha.rc.uab.edu/` +Cloud.rc (OpenStack),`https://cloud.rc.uab.edu/` +Code.rc (GitLab),`https://code.rc.uab.edu/` +Long-Term Storage (LTS),https://s3.lts.rc.uab.edu/ diff --git a/docs/account/xias/_template/revoke_access.md.j2 b/docs/account/xias/_template/revoke_access.md.j2 new file mode 100644 index 000000000..58c2ba83b --- /dev/null +++ b/docs/account/xias/_template/revoke_access.md.j2 @@ -0,0 +1,4 @@ +{% from "_macro/support.md.j2" import contact_support_link %} +!!! important + + If you need to revoke XIAS Guest access to RCS services, please {{ contact_support_link() }}. diff --git a/docs/account/xias/_template/sponsor_responsibility.md.j2 b/docs/account/xias/_template/sponsor_responsibility.md.j2 new file mode 100644 index 000000000..071fef0b6 --- /dev/null +++ b/docs/account/xias/_template/sponsor_responsibility.md.j2 @@ -0,0 +1,3 @@ +!!! important + + By sponsoring an external collaborator, you assume responsibility for managing their access to, and use of, UAB technology systems. diff --git a/docs/account/xias/_template/xias_help_section.md.j2 b/docs/account/xias/_template/xias_help_section.md.j2 new file mode 100644 index 000000000..ed1055107 --- /dev/null +++ b/docs/account/xias/_template/xias_help_section.md.j2 @@ -0,0 +1,9 @@ + +{% from "_macro/support.md.j2" import contact_support_link, help_header %} +{{ help_header(2) }} + +For support with the XIAS web app and XIAS account management, please contact . + +For support with this documentation, please {{ contact_support_link() }}. + +{% include "account/xias/_template/revoke_access.md.j2" %} diff --git a/docs/account/xias/index.md b/docs/account/xias/index.md new file mode 100644 index 000000000..f26605536 --- /dev/null +++ b/docs/account/xias/index.md @@ -0,0 +1,56 @@ +--- +hide: + toc: true +--- + +# Create and Manage External Collaborator (XIAS) Accounts + +UAB uses the XIAS system for managing external collaborator access to technology resources. To access UAB resources, external collaborators must be sponsored for a XIAS account by a UAB employee. When this occurs, the UAB employee is called "Sponsor" and the external collaborator "Guest". + +We recommend Sponsor and Guest stay in close contact during the XIAS account creation process to more quickly identify and resolve any issues that may arise. + +{% include "account/xias/_template/revoke_access.md.j2" %} + + +!!! info + + XIAS stands for External Identity Access Support + + +## What Do We Need Before Starting? + +Before starting, you'll need the following prerequisites. + +- The Sponsor will need: + - an [RCS Account](../rcs/index.md); + - _and_ a list of RCS resources each Guest needs access to; + - _and_ the email address each Guest wants to register with. +- Guests must be able to access their email addresses. + +## How Do I Create a XIAS Account? + +The process for creating and configuring a XIAS account has three phases. The Sponsor is responsible for the first two phases and the Guest is responsible for the third phase. RCS adds a fourth phase, Guest RCS account creation, after the first three XIAS phases. + +The XIAS account creation phases are outlined in the cards shown below. + +{{ + renderer.render_cards( + cards.account.xias.sponsor_site, + cards.account.xias.sponsor_user, + cards.account.xias.guest_instructions, + cards.account.xias.guest_create_rcs, + ) +}} + +## How Do I Manage XIAS Sites and Users? + +Do you already have Sites and Users and want to update URIs, end dates, or which Users can access which Sites? + +{{ + renderer.render_cards( + cards.account.xias.manage_site, + cards.account.xias.manage_user, + ) +}} + +{% include "account/xias/_template/xias_help_section.md.j2" %} diff --git a/docs/account_management/cheaha_account.md b/docs/account_management/cheaha_account.md deleted file mode 100644 index 7d4a407ca..000000000 --- a/docs/account_management/cheaha_account.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -toc_depth: 3 ---- - -# Cheaha Account Management - -These instructions are intended to guide researchers on creating new accounts and managing existing accounts. - -## Creating a New Account - -Creating a new account is a simple, automated, self-service process. To start, navigate to , our [Open OnDemand](../cheaha/open_ondemand/index.md) web portal, and authenticate. The authentication process differs depending on your affiliation. Accounts are available to researchers with the following situations. - -- If you are affiliated with UAB and have a BlazerID, please authenticate using Single Sign-On (SSO). -- If you are affiliated with UAB Medicine, you will need to use your BlazerID to authenticate via Single Sign-On (SSO) instead of your UABMC authentication process. -- If you are an external collaborator and have a XIAS account with access to Cheaha, please authenticate using your XIAS email address as the ID, not automatically generated `xias-XXXXXX-1` ID. -- If you are an external collaborator and do not have a XIAS account, you will need a UAB-affiliated sponsor and will need to follow our [XIAS Guest Account Instructions](xias/guest_instructions.md). Your sponsor will need to follow our [XIAS Site Management](xias/pi_site_management.md) and [XIAS Guest Management](xias/pi_guest_management.md) documentation pages. - -Once you have authenticated, you should see a page that looks like the following. - -![!UAB self registration page.](./images/uab_self_register_001.png) - -The form should be prefilled with your BlazerID or XIAS ID, full name, and email address. If any of these details are incorrect please [Contact Support](../help/support.md). Please also fill out the reason you wish to create an account. To create a Cheaha account, you must check both boxes affirming your acceptance of relevant UAB IT policies. Until both boxes are checked, the "Create Account" button will not be usable. - -When you are ready, click "Create Account" to start the account creation process. You should see a popup notification that looks like the following. After a few moments you should be redirected to our [Open OnDemand](../cheaha/open_ondemand/index.md) web portal. If not, please [Contact Support](../help/support.md). - -![!Account creation notification popup](images/uab_self_register_002.png) - -Welcome to Cheaha and to Research Computing! - -## Managing an Existing Account - -If you already have an account and wish to check it's status, please visit your account status page at . - -### Account in Good Standing - -If your account is in good standing you should see a page like the following. - -![!Account in good standing page.](images/uab_good_standing.png) - -### Account Requires Certification - -We review accounts periodically to ensure the system is being used fairly and as intended. Part of this process is to certify that researchers with accounts still wish to make use of Cheaha. Once per year every researcher will be required to certify their account before making use of Cheaha. In addition, all accounts require certification after being placed on hold (see our [Account on Hold section](#account-on-hold)). This way, we ensure users are engaged in the process of reactivating their account to use our resources. If your account requires certification, you will see the below notification page when logging into our [Open OnDemand](../cheaha/open_ondemand/index.md) web portal. - -![!Account certification notification page.](images/uab_certify_001.png). - -To certify your account, click the button to be taken to the certification form, which should look like the following. - -![!Account certification form.](images/uab_certify_002.png) - -While the certification form looks similar to the new account creation form, please be sure to review all of the information carefully. To certify your account, you must check both boxes affirming your acceptance of relevant UAB IT policies. Until both boxes are checked, the "Create Account" button will not be usable. - -When you are ready, click "Certify Account" to start the account creation process. You should see a popup notification confirming the process is working. After a few moments your account should be certified and you will be free to use Cheaha again. If not, please [Contact Support](../help/support.md). - -### Account on Hold - -Mistakes happen, and sometimes what we thought we programmed wasn't quite what we actually programmed. When these kinds of mistakes occur, excess resources may get used. If this impacts performance or other users excessively, we may put a hold on your account. We may also put a hold on your account if you do not complete [Account Certification](#account-requires-certification) when required. - -Other reasons for holds include, but are not limited to: - -- Inactivity: extended account inactivity. -- Affiliation: [end of affiliation with, or employment by, UAB](./leaving_uab.md). -- Subscription: unsubscribing from the `hpc-announce LISTSERV` mailing list. -- Non-compliance: - - Misuse of Research Computing resources. - - [IT Policy](https://www.uab.edu/it/home/policies) non-compliance. - - [HIPAA](https://www.uab.edu/it/home/policies/compliance/hipaa) or [FERPA](https://www.uab.edu/registrar/ferpa) non-compliance related to use of Cheaha. -- Investigation: issues identified as part of a required review of the account. - -In rare circumstances, we may also place a hold on your account if you possess the sole copy of data not owned by you. - -If your account is on hold, you will see a page like the following. - -![!Account on hold page.](images/uab_on_hold.png) - -If you SSH into the cluster while your account is on hold you will see the following text in your terminal. - -![!Account on hold SSH reply.](images/uab_on_hold_ssh.png) - -If your account is on hold and we have not already contacted you, or you believe the hold to be in error, please [Contact Support](../help/support.md). - -### Authorization Error - -Periodically, we review all researcher accounts to ensure they are authorized to use Cheaha based on affiliation status. If we find a researcher is no longer affiliated with UAB, we may disable the account. If you are not authorized to use Cheaha, you will see a page like the following. - -![!Account authorization error page.](images/uab_auth_error.png) - -If you believe this to be in error, please [Contact Support](../help/support.md). - -## What Can I Do With My Account? - -Research Computing offers services addressing a wide range of needs for researchers at UAB, including students, staff, and faculty, as well as for both Labs and research cores. - -We're always happy to provide support for your Research Computing needs, you need only [Contact Support](../index.md#how-to-contact-us). - -### For Students, Staff, and Faculty - -- [Get Started with Open OnDemand](../cheaha/open_ondemand/index.md) -- [Additional Learning Resources](../education/training_resources.md) -- [Data Science Journal Club Course](../education/courses.md#data-science-journal-club-course) - -### For Lab PIs and Core Directors - -- [No-cost storage offerings](../data_management/index.md#what-type-of-storage-do-i-need) - - [GPFS](../data_management/index.md#what-shared-storage-solutions-are-available): Hot storage, compute adjacent, directly accessible from Cheaha - - [LTS](../data_management/lts/index.md): Cool storage, large capacity - - [Transfer data with Globus](../data_management/transfer/globus.md) -- [Batch computing](../cheaha/slurm/introduction.md) - - Interactive applications in [Open OnDemand](../cheaha/open_ondemand/index.md) - - [HPC Desktop](../cheaha/open_ondemand/hpc_desktop.md) - - [Jupyter Notebook](../cheaha/open_ondemand/ood_jupyter_notebook.md) - - [JupyterLab](../cheaha/open_ondemand/ood_jupyterlab.md) - - [RStudio](../cheaha/open_ondemand/ood_rstudio.md) - - [Matlab](../cheaha/open_ondemand/ood_matlab.md) - - [GPUs](../cheaha/slurm/gpu.md) -- [On-prem cloud computing](../uab_cloud/index.md) - - [Tutorial](../uab_cloud/tutorial/index.md) - - [Web servers](../uab_cloud/remote_access.md#make-instances-publically-accessible-from-the-internet) - - If you are unable to find what you need, please feel free to [Contact Support](../index.md#how-to-contact-us). - -## Cheaha Account and Group Membership FAQ - -Our Cheaha system is robust, but errors may occur due to general platform connectivity issues or missing components. Below are FAQs for self-service Cheaha account creation and a troubleshooting guide for common issues: - -- **Which credentials should I use?** Please visit [How Do I Login to Research Computing Services](../account_management/index.md#how-do-i-login-to-research-computing-services). -- **What do I do if I'm waiting for it to finish for longer than a couple of minutes?** - - - Try closing and restarting your browser, then trying again. - - Try clearing site data for , then trying again. - - Try logging in on a Private Browsing window, then trying again. - - Try waiting a few hours, then trying again. - -- **What should I do to access shared storages and recognize my group membership after being added to a group on Cheaha?** - - - **Do you have any processes/connections on `cheaha.rc.uab.edu`**? - - - Please exit and log back in. - - If you have active Tmux/Screen sessions, you will need to terminate those as well, log out, log back in and start Tmux. - - - **Do you have an active Open OnDemand session?** - - - In Open OnDemand (), navigate to the green navigation bar in the top right corner. Look for the `Help` or `Developer` dropdown menu and click on it. Then, click `Restart Web Server`. Once the restart is complete, please try again. - - - **Do you have one or more OOD HPC Desktops running?** - - - Terminate the desktops and start new ones. - -## Leaving UAB - -Please see our [Leaving UAB page](./leaving_uab.md). diff --git a/docs/account_management/gitlab_account.md b/docs/account_management/gitlab_account.md deleted file mode 100644 index 6c98a8c64..000000000 --- a/docs/account_management/gitlab_account.md +++ /dev/null @@ -1,198 +0,0 @@ -# UAB GitLab Overview and Registration - -Welcome to UAB GitLab! This is a UAB-specific [GitLab](https://about.gitlab.com/). GitLab is similar to [GitHub](https://github.com/), but hosted here at UAB on secure servers. - -## GitLab Use Cases - -### For Researchers - -GitLab can be used: - -- For reproducibility - - Analysis and software code can be kept in one, central repository everyone can use instead of spread across multiple computers/places. - - Code can be versioned and tracked as it changes over time. - - Software versions can be recorded, virtual environments can be documented, and containers can be recorded to help future-proof analyses. -- Collaboration - - GitLab is a central place to create code, edit, and track needed code changes (issues) with your lab and collaborators. - - Multiple people can use, modify, and merge changes in code while communicating with the broader team all along the way. -- Security - - Unlimited private repositories for internal code projects. - - Set behind UAB authentication. - -### For Software Developers (And Researchers!) - -UAB GitLab is useful for software developers. It is a single application for the entire software development lifecycle. From project planning and source code management to continuous integration (CI) and continuous deployment (CD), monitoring, and security. - -Our on-premises GitLab instance may be found at . - -## UAB GitLab Registration - -### UAB-Affiliated Researcher Registration - -If you are a UAB affiliated researcher and have a BlazerID, you may create an account by logging in at the site above using the `ldap` tab. Please use your single sign-on (SSO) credentials. - - -!!! note "Please use BlazerID and password instead of UABMC credentials" - - Please use your BlazerID and BlazerID password for UAB GitLab. UABMC credentials are a different sign in system and will likely not work. Central IT groups like Research Computing do not have a way to access UABMC credentials. - - -![!gitlab login pane with ldap tab selected](./images/gitlab_researcher_ldap.png) - -## UABMC Researcher Registration - -Please use your BlazerID and BlazerID credentials to sign in following the directions for UAB-Affiliated Researchers. UABMC credentials should not be used for UAB GitLab. - -## XIAS External Collaborator Registration - -If you are a collaborator with a XIAS account you'll need to follow a different procedure. - -1. Ensure that your sponsor has included `https://code.rc.uab.edu` in the list of approved URIs on the XIAS configuration page. -1. Email providing your full name, XIAS account email address, and sponsor. -1. UAB Research Computing will create the account. -1. You will recieve an email from `code.rc.uab.edu` with a link to create a password. -1. Navigate to . -1. Click the `Standard` tab. -1. In the `Username or email` field type the part of your XIAS email address before the `@` symbol. Do not include the `@` symbol or anything after it. -1. Fill out the `Password` field with the GitLab password you created in Step #4. -1. Click `Sign in`. - -![!gitlab login pane with standard tab selected](./images/gitlab_researcher_standard.png) - - -!!! warning - - XIAS account researchers can only be granted access if their sponsor adds the GitLab URL to the list of approved URIs. Please see [XIAS Sites](./xias/pi_site_management.md) for more information. - - -## UAB GitLab Roles and User Permissions - -Managing roles and user permissions within GitLab is essential for maintaining control over repositories and collaboration. Within UAB Research Computing's GitLab instance, a user (Owner) can assign and update user roles in a group. There are several roles for users within GitLab, and these roles determine the level of permissions a user will have within a Group or project. In GitLab, permissions are organized in a hierarchical group/project tree structure. At the top is a Group, which can contain subgroups and individual projects. This structure makes permission control easy to manage. Groups can represent schools, faculty, departments, labs or cores, while projects hold the actual code, issues, and CI/CD configurations for grants and research they administer. - -The available default roles within a group/project are listed in the table; - -{{ read_csv('account_management/res/gitlab_roles.csv', keep_default_na=False) }} - -A user assigned the "Guest" role has the least permissions, and the "Owner" has the most permissions. The table summarizes key features and permissions per user role in a Group/Project. For a complete list of permissions each role can perform, please see [GitLab documentation for user permissions](https://docs.gitlab.com/user/permissions/). In the section [Assigning a User's GitLab Role](#assigning-a-users-gitlab-role), you will see a guide to create, and assign user roles within your GitLab project. - -## Why Groups and Projects Are Important - -With UAB GitLab’s instance of Group and Project structure, we offer a powerful way to mirror how your research lab or programs are structured. When we consider the organizational setup at UAB, where a Core oversees several specialized Labs. Each lab is led by a different PI, researcher or department. Within each Lab, multiple projects are being run, possibly by different teams, postdocs, or students. GitLab’s inheritance Group to Project model, shows Groups can contain subgroups and projects, making it possible to organize this exact structure digitally (Core->Lab/Department->Projects). The Core entity at UAB can be represented as a top-level group, each Lab as a subgroup, and individual projects (e.g., datasets, analysis pipelines, or software tools) as repositories within those subgroups. - -This structure helps to maintain a clear navigation system, it also ensures efficient role and permission management. The Core can assign high-level oversight roles at the Group level, while Labs can manage their own subgroups independently. Developers and researchers can be granted access only to the projects they work on, without exposing unrelated projects or sensitive data they should not have access to, adhering to the principle of least privilege. Combined with GitLab’s role inheritance and ability to override roles at lower levels, this design promotes scalability, security, and accountability, while supporting collaborative research across a complex institutional environment like UAB. - -## Assigning a User's GitLab Role - -For UAB's GitLab instance, only a user with the role "Owner" can assign or change a GitLab role for a user across "Projects" or "Groups". Whereas, a "Maintainer" has project-level privileges and can only manage users that are part of a "Project" within a "Group", the "Owner" has group-wide privileges that extend to the "Projects" under their "Group". Remember, for a User to be added to a Group, they would need to have a UAB GitLab account set up. Please see the [UAB Affiliated Researcher Registration](#uab-affiliated-researcher-registration) page for setting one up. - -The following instructions are to guide you in creating a group and/or assigning user roles as a group owner. - -### Creating a Group in UAB's GitLab Instance - -1. Log in to the [UAB Research Computing GitLab instance](https://code.rc.uab.edu/users/sign_in) using your UAB Credentials. - - ![!image showing UAB RC GitLab Landing Page](./images/uab-gitlab-landingpage.png) - -1. Click on the "Groups" menu option. - - ![!image showing Logged-in interface](./images/uab-gitlab-group1.png) - -1. Select "New group". - - ![!image showing Groups a user has access to on GitLab, with the New group button highlighted](./images/uab-gitlab-group2.png) - -1. Now select the "Create group" option. You may select the "Import group" option, if you already have projects and their associated data from a different GitLab instance ready. For this guide, we are assuming this is not the case, and you are setting up a new Group. - - ![!image showing the Create group and Import group option, with the Create group option highlighted](./images/uab-gitlab-creategrp.png) - -1. Fill out the form to create your group, make sure to include a name, and appropriate "Visibility level". There are three (3) levels for visibility, pick the option meeting your needs. Click on the "Create group" option, and this completes the Group creation process. - - ![!image showing the form to Create group, with the Group name, Visibility level and Create group options highlighted](./images/uab-gitlab-creategrp2.png) - - - !!! note - - GitLab allows you to define Group visibility using "Public", "Internal", or "Private" settings. A public Group is visible to and can be cloned by anyone, even without a GitLab account. An internal Group is visible to any authenticated UAB GitLab user, but access to contribute is still controlled by roles. A private Group is only visible and accessible to users who have been explicitly granted access. These settings work in tandem with permissions to control both who sees what and what they can do in a Group. See [GitLab documentation](https://docs.gitlab.com/user/public_access/) for more information. - - -1. Now that your group has been created, we can [add users with varying roles](#add-and-assign-user-roles-within-a-group-or-project) that grant different user permissions. - - ![!image showing a list of Groups](./images/uab-gitlab-grplist.png) - -### Creating a Project in UAB's GitLab Instance - -As a Maintainer or Owner you can create Projects from within a Group. Steps 1 and 2 are same as the instructions for [Creating a Group](#creating-a-group-in-uabs-gitlab-instance), there is a slight deviation at the third step. - -1. Log in to the [UAB Research Computing GitLab instance](https://code.rc.uab.edu/users/sign_in) using your UAB Credentials. - - ![!image showing UAB RC GitLab Landing Page](./images/uab-gitlab-landingpage.png) - -1. Click on the "Groups" menu option. And select the appropriate Group. - - ![!image showing Logged-in interface](./images/uab-gitlab-grouptest.png) - -1. From within the group, Select "New project". - - ![!image showing Groups a user has access to on GitLab, with the New group button highlighted](./images/uab-gitlab-projectgroup.png) - -1. Now select from one of the options to create new project, in this example we use the "Create blank project" option. You may select the "Import project" option, or "Create from template" option. For this guide, we are assuming this is not the case, and you are setting up a new Project. - - ![!image showing the Create new Project options, with the Create group option highlighted](./images/uab-gitlab-createproject.png) - -1. Fill out the form to create your Project, make sure to include a name, and appropriate "Visibility level". There are three (3) levels for visibility, pick the option meeting your needs. Click on the "Create project" option, and this completes the Project creation process. - - ![!image showing the form to Create project, with the Project name, Visibility level and Create project options highlighted](./images/uab-gitlab-createproject2.png) - - - !!! note - - GitLab allows you to define project visibility using "Public", "Internal", or "Private" settings like in a group. A public project is visible to and can be cloned by anyone, even without a GitLab account. An internal project is visible to any authenticated UAB GitLab user, but access to contribute is still controlled by roles. A private project is only visible and accessible to users who have been explicitly granted access. These settings work in tandem with role-based permissions that control who can see what and what they can do in a project. See [GitLab documentation](https://docs.gitlab.com/user/public_access/) for more information. - - -1. Now that your project has been created, we can [add users with varying roles](#add-and-assign-user-roles-within-a-group-or-project) that grant different user permissions. To see members in your project, select the "Manage" option and then select the "Members" option. This will take you to the list of members who are part of that project. - - ![!image showing the list of Members in a Project](./images/uab-gitlab-projectlist.png) - -### Add and Assign User Roles Within a Group or Project - -1. Click on the Group/Project, you have requisite permissions to (Owner for Groups, Owner or Maintainer for Projects). From within your Group/Project, click on the "Manage" pane located to the left of your Group/Project. And then click on "Invite members". If you are already part of another Group, dependent on the permissions you have in those Groups, you may be able to add all members of a Group with the "Invite a group" option, but for this guide, we are focusing on the "Invite members" option. - - ![!image showing Members list of a Group in GitLab, with the "Manage", "Members", "Invite a group" and "Invite members" options highlighted](./images/uab-gitlab-invitemembers.png) - - - !!! note - - Please note, GitLab follows a "Group to Project" inheritance model, where a user added to a Group, would inherit that same role, when a new Project is created unless that role is changed. For instance, a user maybe assigned a Guest role at the Group level, but may have a higher role assigned at the project level. - - -1. The "Invite members" option, would open up to a mini window that shows an interface to invite members with their "Username, name or email address", an option to "Select a role", an option that allows you to set "Access expiration date" for a user, and the "Invite" button. - - ![!image showing options from selecting "Invite members"](./images/uab-gitlab-invitemembers2.png) - - The option "Select a role" is where you select what kind of role, you want the listed user(s) to have. Please refer to this [section](#uab-gitlab-roles-and-user-permissions) to see what each user role has permissions to do within your Group/Project. - - ![!image showing Roles available from the "Select a role" option](./images/uab-gitlab-invitemembers3.png) - - - !!! note - - You can only add uab.edu entities or domain emails to GitLab, you will get an error like in the image below if you do otherwise. Please see our section on [UAB GitLab Registration](#uab-gitlab-registration) to address adding external collaborators before attempting the prior steps. - - ![!image showing error from adding non-UAB email or entities](./images/uab-gitlab-domaindiff.png) - - -1. Now you can see a list of Group/Project members, showing their "Account" i.e. their Name and BlazerID, their "Source" i.e. how they joined the group, their "Role" i.e. level of permission within your Group, and "Expiration" i.e. how long they will have access to the group, unless this is changed, the default option is for a user to have access indefinitely. In this guide, one of the user's has an expiration of `2025-04-14`, after this date the user will no longer have access to your Group/Project. In the last column we have "Activity" i.e. additional metadata for the user. - - ![!image showing members in a Group](./images/uab-gitlab-grpmembers.png) - - You can also remove a user from your Group/Project, by clicking on the "More actions" button, the three (3) vertical lines to the right of an Account, and click the "Remove member" option. - - - !!! note - - To manage security risks please apply the principle of Least Privilege when assigning roles. The principle states that users should be given the minimum level access to perform their roles. This is to mitigate security risks and operational errors. This principle ensures you limit members of your Group who can intentionally or unintentionally make destructive or irrevocable changes. - - -1. You can also change or update a user's role, by selecting one of the other options provided under the "Role" column for an Account. This changes the user's role within the Group/Project. - - ![!image showing roles a member can be changed to or updated to in a Group](./images/uab-gitlab-updaterole.png) diff --git a/docs/account_management/images/gitlab_researcher_ldap.png b/docs/account_management/images/gitlab_researcher_ldap.png deleted file mode 100644 index 00081ac0f..000000000 Binary files a/docs/account_management/images/gitlab_researcher_ldap.png and /dev/null differ diff --git a/docs/account_management/images/gitlab_researcher_standard.png b/docs/account_management/images/gitlab_researcher_standard.png deleted file mode 100644 index 013a42184..000000000 Binary files a/docs/account_management/images/gitlab_researcher_standard.png and /dev/null differ diff --git a/docs/account_management/images/uab_auth_error.png b/docs/account_management/images/uab_auth_error.png deleted file mode 100644 index c3bc53414..000000000 Binary files a/docs/account_management/images/uab_auth_error.png and /dev/null differ diff --git a/docs/account_management/images/uab_certify_001.png b/docs/account_management/images/uab_certify_001.png deleted file mode 100644 index 1e42a4792..000000000 Binary files a/docs/account_management/images/uab_certify_001.png and /dev/null differ diff --git a/docs/account_management/images/uab_certify_002.png b/docs/account_management/images/uab_certify_002.png deleted file mode 100644 index 69ab6a533..000000000 Binary files a/docs/account_management/images/uab_certify_002.png and /dev/null differ diff --git a/docs/account_management/images/uab_good_standing.png b/docs/account_management/images/uab_good_standing.png deleted file mode 100644 index bc9aaaa87..000000000 Binary files a/docs/account_management/images/uab_good_standing.png and /dev/null differ diff --git a/docs/account_management/images/uab_on_hold.png b/docs/account_management/images/uab_on_hold.png deleted file mode 100644 index 8f2929d31..000000000 Binary files a/docs/account_management/images/uab_on_hold.png and /dev/null differ diff --git a/docs/account_management/images/uab_on_hold_ssh.png b/docs/account_management/images/uab_on_hold_ssh.png deleted file mode 100644 index 23b4becd2..000000000 Binary files a/docs/account_management/images/uab_on_hold_ssh.png and /dev/null differ diff --git a/docs/account_management/images/uab_self_register_001.png b/docs/account_management/images/uab_self_register_001.png deleted file mode 100644 index 81ed625f4..000000000 Binary files a/docs/account_management/images/uab_self_register_001.png and /dev/null differ diff --git a/docs/account_management/images/uab_self_register_002.png b/docs/account_management/images/uab_self_register_002.png deleted file mode 100644 index ed27bb112..000000000 Binary files a/docs/account_management/images/uab_self_register_002.png and /dev/null differ diff --git a/docs/account_management/index.md b/docs/account_management/index.md deleted file mode 100644 index 20e1cbc41..000000000 --- a/docs/account_management/index.md +++ /dev/null @@ -1,37 +0,0 @@ -# Account Management - -## User Accounts and Responsibilities - -Research Computing at UAB provides shared resources for researchers, where responsible and professional use of Cheaha accounts, storage, and computational resources is expected to maintain system integrity and support collaborative research. Please refer below for the eligibility requirements and responsibilities of Research Computing services users. - -{{ read_csv('account_management/res/user_responsibilities.csv', keep_default_na=False) }} - -### All Users Responsibilities - -- Regularly clearing `/scratch`. -- Adherence to [UAB IT policies](https://www.uab.edu/it/home/policies). -- Request computational resources reasonably. Refer to our [compute resource estimation](../cheaha/job_efficiency.md#estimating-compute-resources). -- [Responsible Conduct of Research training](https://www.uab.edu/research/home/responsible-conduct-of-research). -- [Annual account certification of Cheaha account](../account_management/cheaha_account.md#account-requires-certification). -- All Cheaha account users working with Protected Health Information (PHI) data are responsible to review [HIPAA policies](https://www.uab.edu/it/home/policies/compliance/hipaa) and -[HIPAA training](https://www.uab.edu/compliance/areas-of-focus/privacy/training). - -## How Do I Create a Research Computing Account? - -- **Cheaha Account**: Creating a Cheaha account is currently a self-service process. Both UAB employees, students, and external collaborators can create a Cheaha account by visiting [creating a Cheaha account page](./cheaha_account.md). -- **GitLab Account**: If you are a UAB-affiliated researcher and have a BlazerID, you may create an account by visiting [GitLab registration steps for UAB Employees and Students](./gitlab_account.md#uab-gitlab-registration). If you are a collaborator with a XIAS account, you will need to follow the procedure in [External Collaborators registration](./gitlab_account.md#xias-external-collaborator-registration). -- **Cloud.rc Account**: To get your Cloud.rc account, please contact [Support](../help/support.md). For detail information on how to access it, please visit our [Cloud.rc](../uab_cloud/index.md) page. - -## How Do I Login to Research Computing Services? - -- **Cheaha**: To login to Cheaha: - - UAB Employees and Students: use your BlazerID. - - External Collaborators: use your XIAS email address. - - For detail login information, please visit [accessing Cheaha](../cheaha/getting_started.md#accessing-cheaha) page. If accessing through Open OnDemand, our online portal, [Duo 2FA](https://www.uab.edu/it/home/security/2-factor) may be required. - -- **GitLab**: To login to the GitLab, the UAB Employees and Students require a BlazerID, while External Collaborators require XIAS email. For detail login information visit the [UAB Employees and Students GitLab Registration](./gitlab_account.md#uab-gitlab-registration) and [External Collaborators GitLab Registration](./gitlab_account.md#xias-external-collaborator-registration) pages respectively. - -- **Cloud.rc**: To access the Cloud.rc, you must be on the campus network. For off-campus access, use the [UAB Campus VPN](https://www.uab.edu/it/home/tech-solutions/network/vpn), which requires [Duo 2FA](https://www.uab.edu/it/home/security/2-factor). -UAB employees and students can log in using their BlazerID, while External Collaborators use their XIAS email. For login details, visit our [Cloud.rc](../uab_cloud/index.md#first-steps) page. - -If you are unable to find what you need, please [Contact Support](../index.md#how-to-contact-us). diff --git a/docs/account_management/leaving_uab.md b/docs/account_management/leaving_uab.md deleted file mode 100644 index 970a49a35..000000000 --- a/docs/account_management/leaving_uab.md +++ /dev/null @@ -1,78 +0,0 @@ -# Leaving UAB - -If your life and career plans take you away from UAB, then this article is designed to help you. We hope to give you a better understanding of your responsibilities and what to expect for your account and data. - -All research data produced as part of UAB research is, by policy, owned by UAB. Funding agencies (e.g. NIH) often have strict data retention and sharing regulations. Transferring UAB-owned and/or agency funded data requires the involvement of the [Office of Research](https://www.uab.edu/research/home/about/contact-us), specifically the [Office of Sponsored Programs (OSP)](https://www.uab.edu/research/home/osp-about/contact). - -If you have questions, concerns, or any doubt after reading this page, we highly recommend [contacting us](../help/support.md). - - -!!! important - - The contents of this article apply only to research data. For administrative data you will need to discuss with the approriate UAB Administrative units. You can contact for more information on what to do with administrative data. - - -## What Happens to My Cheaha Account? - -Your Cheaha account will be available and accessible for 30 days following your last day in a UAB-affiliated position. This 30-day grace period is a temporary extension of access that allows faculty/students leaving UAB in good standing to read and transfer their data from the Cheaha system before the account is deactivated. - -The same 30-day grace period applies to all other Research Computing platform accounts. - -If you anticipate needing more than 30 days to complete your data transfers, [contact us](../help/support.md) as soon as possible so we can make arrangements or work to improve data transfer efficiency. - -## What Happens to Data in My Individual Storage Allocations? - -Data in your individual storage allocations, on all storage platforms, will be retained for the full grace period. We recommend making a plan for your data. Download any personal, non-UAB-owned data you wish to keep. [Transfer any UAB-owned data to an appropriate location.](#what-should-i-do-with-uab-owned-data) - -## What Should I Do With UAB-Owned Data? - -If you are a student or staff, please make arrangements with your faculty supervisor to transfer any UAB-owned data to the appropriate shared storage. If you have multiple faculty supervisors, please do this for each of them. - -If you are a faculty supervisor or Core director, what to do with the data depends on the specifics of your situation. - -- [Lab Shared Storage](#what-are-my-responsibilities-for-lab-shared-allocations) -- [Core Shared Storage](#what-are-my-responsibilities-for-core-shared-allocations) - -## What if I Will Be Hired or Rehired in a New Role? - -Your data will be available for the full grace period. If your hire date is later than the end of the grace period, please [contact us](../help/support.md) to discuss. - -## What if I Plan to Have an Ongoing Collaboration? - -If you plan to continue collaborating with other researchers and need to manage data or perform analyses on Cheaha, you will need to create a [XIAS account](./xias/index.md). To create the account, you will need a UAB-affiliated sponsor. Once the account has been created, please contact us and we can assist with transferring data in your former individual storage allocation to your new allocation. - -## What Are My Responsibilities for Lab Shared Allocations? - -If you are responsible for lab shared allocations on Research Computing storage platforms, you have certain responsibilities for the data within them. Transferring UAB-owned data requires the involvement of the [Office of Research](https://www.uab.edu/research/home/about/contact-us), specifically the [Office of Sponsored Programs (OSP)](https://www.uab.edu/research/home/osp-about/contact). - -For each dataset or project, which option is ideal depends on the state of the project. - -- Transfer responsibility of the data to a successor (retiring)? - - 1. Make the appropriate arrangements with relevant administrative units (e.g., Office of Research and OSP). - 1. [Globus](../data_management/transfer/globus.md) may be used to efficiently and robustly transfer the data from one directory on Cheaha to another. Please [contact us](../help/support.md) for more details. - -- Transfer the data to a new instutition (moving)? - - 1. Contact the Office of Research to create a "Data Use Agreement" with your new institution. Read more on the [OSP Site](https://www.uab.edu/research/home/osp-federal-contracts/fc-other/data-use-agreements). - 1. [Contact us](../help/support.md) and your new institution's Research Computing equivalent to determine how to transfer data efficiently. - -- Comply with funding agency data retention regulations (retiring)? - - - Find a UAB-affiliated successor to manage the data for you in your absence. - - _OR_ Find an archival service suitable for long term data retention. - -- Something else? Please [contact us](../help/support.md). - -## What Are My Responsibilities for Core Shared Allocations? - -Cores should not assume responsibility for any of the research data they produce or acquire. - -If the Core will continue operating, then it is assumed there will be a successor. Take whatever necessary administrative steps to transfer control and responsibility for Core operations. Things that may need to be transfered: - -- [GPFS (Cheaha) shared allocation](../data_management/cheaha_storage_gpfs/project_directories.md). -- [LTS shared allocation](../data_management/lts/index.md). -- [OpenStack Shared Projects](../uab_cloud/sharing_cloud_environment.md). -- Service account, shared mailboxes, and other shared resources not managed by Research Computing, but which may have an impact on Core operations relating to Research Data acquisition and transfer, such as [Globus](../data_management/transfer/globus.md). - -If the Core will cease operating, please [contact us](../help/support.md) to make arrangements to ensure final disposition of all research data. diff --git a/docs/account_management/xias/guest_instructions.md b/docs/account_management/xias/guest_instructions.md deleted file mode 100644 index e352cdfb8..000000000 --- a/docs/account_management/xias/guest_instructions.md +++ /dev/null @@ -1,70 +0,0 @@ -# Guest Instructions - -These instructions are for guests who have been registered by UAB faculty and staff to use internal UAB resources. Once a request for a XIAS account has been made by your UAB sponsor, you will need to follow these instructions to complete the XIAS registration and obtain access to UAB resources. All of the links used on this page are available at the [UAB XIAS Guest Users](https://apps.idm.uab.edu/xias/top) page. - -## Create Account - -1. The first email you receive should be a notification that a request has been made to add you as a XIAS user. This email will include the project(s)/site(s) you're being added to. - - ![!Email notification indicating a request has been made to register the user receiving the email. Contains a list of sites the request has been made for. Additional information is provided regarding the next email.](./images/xias_guest_001.png) - -1. The next email you receive should contain instructions on how to register your account. This email may take an hour or so to arrive after the first. It will contain an invite code that you must enter at the XIAS website, along with the email address used to register you. - - ![!Email with instructions for completing XIAS user registration. The instructions include a link to the UAB XIAS Guest Users page https://apps.idm.uab.edu/xias/top and an invite code for registration.](./images/xias_guest_002.png) - -1. Navigate to the link in the email. Please practice good internet hygiene and copy the link text, instead of clicking the link! As of the time of writing the link will be to the [UAB XIAS Guest Users](https://apps.idm.uab.edu/xias/top) page. Once at the main page, click the "Enter Invite or Reset Code" link. - - ![!Main UAB XIAS Guest Users page. Links are in the menu at left and include the "Enter Invite or Reset Code" link.](./images/xias_guest_003.png) - -1. You will be taken to the "Register XIAS Account" page. Enter the email address used to register you for a XIAS account, and the code from the email you received with registration instructions. Then click proceed. - - ![!Register XIAS Account form. The form requires an email and invite code. A proceed button is highlighted.](./images/xias_guest_004.png) - -1. Enter your first and last names, then click proceed. - - ![!Form requiring first and last name of the user. A proceed button is highlighted.](./images/xias_guest_006.png) - -1. Enter a password that will be used with your XIAS account. This password can be changed later, and your account can be recovered if the password is lost. Click proceed. - - ![!Form requiring password and confirmation of password. A proceed button is highlighted.](./images/xias_guest_007.png) - -1. You will be taken to a confirmation page. If everything is acceptable, click proceed. Otherwise click edit next to the incorrect field. Your XIAS email cannot be changed. If the email is not correct you will need to communicate with your sponsor to start the entire process over from the beginning. - - ![!Confirmation page summarizing previous forms. Listed are email, name and password. Password is obfuscated. Edit buttons are to the right of name and password. A proceed button is highlighted.](./images/xias_guest_008.png) - -1. You should be taken to a page indicating success. Please carefully read the page and follow any instructions. If you do not see a success page, please contact your sponsor about next steps. - - ![!Registration success page with additional instructions and suggestions.](./images/xias_guest_009.png) - - Following this step, your account registration is complete and you should be able to access the resources you have been granted permission to use. Most internal UAB systems use a Single Sign-On (SSO) to simplify and standardize logging in. For those sites that don't you will need to activate your account manually. Please follow the [Next Steps Guide](index.md#what-is-next-and-how-to-login-to-services) to access [Cheaha](https://rc.uab.edu) via your XIAS account. - -1. To manually activate accounts for resources that do not use SSO click the "Activate (Sync) Accounts" link on the left hand navigation pane. Fill out the form using the email used to register the XIAS account and the current password. - - ![!Activate (sync) accounts form. Form requires email address and current password.](./images/xias_guest_activate_accounts.png) - -## Required Software for Research Computing Access - -Research computing software requires security software be installed on your devices in order to login. [Duo two-factor authentication (2FA)](https://www.uab.edu/it/home/security/2-factor) software is required on your mobile to device to access any Single Sign-on services. [UAB Campus VPN access software](https://www.uab.edu/it/home/tech-solutions/network/vpn) is required for some services when connected from outside the UAB internal network. Accessing the UAB Campus VPN also requires Duo 2FA. - -Below is a list of Research Computing services and their required software. - -- Cheaha: Duo 2FA -- Cloud.rc: UAB Campus VPN and Duo 2FA if off-campus - -## Change Password and Recover From Lost Password - -To change your password, or recover your account in case of a lost password, please click the "Change XIAS Password" link in the left hand panel of the main page. Once there, follow the instructions on the form. - -![!Change XIAS Password page.](./images/xias_guest_change_password.png) - -## Resend Invite Code - -If your invite code has expired, you can have a new invite code sent to you by clicking the "Resend Invite Code" link in the left hand panel of the main page. Once there, follow the instructions on the form. - -![!Resend Invite Code page.](./images/xias_guest_resend.png) - -## Guest IT Info - -For more information on UAB IT policies and other useful and helpful information, please click the "UABIT Guest User info" link. - -![!Guest IT Info landing page.](./images/xias_guest_it_info.png) diff --git a/docs/account_management/xias/images/xias_guest_003.png b/docs/account_management/xias/images/xias_guest_003.png deleted file mode 100644 index 96bd050d0..000000000 Binary files a/docs/account_management/xias/images/xias_guest_003.png and /dev/null differ diff --git a/docs/account_management/xias/images/xias_guest_004.png b/docs/account_management/xias/images/xias_guest_004.png deleted file mode 100644 index ec4f2ebcb..000000000 Binary files a/docs/account_management/xias/images/xias_guest_004.png and /dev/null differ diff --git a/docs/account_management/xias/images/xias_guest_007.png b/docs/account_management/xias/images/xias_guest_007.png deleted file mode 100644 index edd09c95b..000000000 Binary files a/docs/account_management/xias/images/xias_guest_007.png and /dev/null differ diff --git a/docs/account_management/xias/images/xias_guest_008.png b/docs/account_management/xias/images/xias_guest_008.png deleted file mode 100644 index 22400d270..000000000 Binary files a/docs/account_management/xias/images/xias_guest_008.png and /dev/null differ diff --git a/docs/account_management/xias/images/xias_users_add_000.png b/docs/account_management/xias/images/xias_users_add_000.png deleted file mode 100644 index 6c06b5ae5..000000000 Binary files a/docs/account_management/xias/images/xias_users_add_000.png and /dev/null differ diff --git a/docs/account_management/xias/index.md b/docs/account_management/xias/index.md deleted file mode 100644 index 270180925..000000000 --- a/docs/account_management/xias/index.md +++ /dev/null @@ -1,30 +0,0 @@ -# External Collaborator (XIAS) Accounts - -This segment of the docs has instructions for managing and creating XIAS accounts for external collaborators. - -External collaborators require XIAS accounts to access Cheaha. Obtaining an account requires a UAB-employed sponsor, typically a research PI, who will claim responsibility for the external collaborator. The XIAS account creation process is initiated by the sponsor, not by the external collaborator. - -An overview of creating an external collaborator account: - -1. The sponsor must first: - 1. [Create and manage XIAS Sites](pi_site_management.md) - 1. [Create and manage XIAS Guests](pi_guest_management.md) -1. The guest must then [Create a XIAS Guest Account](guest_instructions.md) - -We recommend the sponsor and guest stay in close contact during the process in case anything unexpected occurs. If you encounter difficulties with any part of the XIAS website process, please contact . If you encounter difficulties with the Cheaha account creation portion at the Open OnDemand web portal, please contact [Support](../../help/support.md) - -## What Is Next and How to Login to Services? - -To login to [Cheaha](../../cheaha/getting_started.md) and [GitLab](../gitlab_account.md), you need to use your XIAS email address (full email address complete with domain name) and the password used to create your XIAS account. To access the Cloud.rc, you first need to request an account. Please follow instructions found here at [Cloud.rc](../../uab_cloud/index.md#first-steps) to initiate the request. - -For further guidance on how to proceed and what steps to take next, please refer to the following documentation pages. - - -!!! warning - - Before proceeding with any of the resources below, be sure you have been granted authorization to those particular resources by your Sponsor. - - -- [How do I create a Cheaha account?](../cheaha_account.md) -- [How do I get access to GitLab?](../gitlab_account.md) -- [How do I get access to Cloud.rc (OpenStack)?](../../uab_cloud/tutorial/index.md) diff --git a/docs/account_management/xias/pi_guest_management.md b/docs/account_management/xias/pi_guest_management.md deleted file mode 100644 index 50ecf1828..000000000 --- a/docs/account_management/xias/pi_guest_management.md +++ /dev/null @@ -1,83 +0,0 @@ -# Managing UAB XIAS Users - - -!!! note - - These instructions are intended for use by UAB-employed PIs to organize external collaborators, also known as guests. UAB PIs: Please direct guests [here](guest_instructions.md) for instructions on creating their accounts. - - - -!!! important - - To complete these steps you will first need to createa a [Project/Site](pi_site_management.md) - - -UAB XIAS User management allow UAB faculty and staff to grant external collaborators access to specific resources on the internal UAB Campus Network. All XIAS users must be connected with at least one site, so you'll need to create one at the [UAB XIAS User Management Webpage](https://idm.uab.edu/cgi-cas/xrmi/sites). All XIAS Users must also have an expiration date. - -## Adding Users - -Before adding users, have a list of user emails handy for the site you wish to add users to, as well as expiration dates for each user. You will need to create a [Project/Site](pi_site_management.md) before you can add external collaborators. - -1. To start go to the [UAB XIAS User Management Webpage](https://idm.uab.edu/cgi-cas/xrmi/sites) and click Manage Users in the left menu. - -1. Select the Project/Site you wish to add users to from the drop down box. - - ![!Select Project/Site drop down box opened with a site highlighted by the mouse cursor.](./images/xias_users_add_001.png) - -1. Click "Register" to open a form for adding new users. - - ![!User registration form with checked Checkbox whose label has the previously selected site. Form also has End Date textbox and unlabeled text box which accepts a list of email addresses.](./images/xias_users_add_002.png) - -1. Fill in the form. All fields are required. - - 1. **Checkbox list** - Leave the site checked. - 1. **End date** - An expiration date for the users being added. Cannot be longer than the end date for the selected Project/Site. - 1. **Text box** - Enter a list of e-mail addresses for users to add. - - ![!Completed user registration form.](./images/xias_users_add_003.png) - -1. Click "Submit" to move to a confirmation page. - - ![!Confirmation page with table containing emails entered on user registration form, one per row.](./images/xias_users_add_004.png) - -1. Check the emails are correct and click "Add" to submit the information Emails will be sent to all email addresses for next steps. You will be redirected to the UAB XIAS User Management Webpage, which should now have the text "Registration successful." near the top. - - ![!UAB XIAS User Management Webpage with the text Registration successful.](./images/xias_users_add_005.png) - -1. To complete their registration, please direct your external collaborators to the [UAB XIAS Guest Users page](https://idm.uab.edu/xias/top). When they have completed their registration, you should receive an email like the following. - - ![!Email sample received following XIAS user registration. Includes user name and email as well as sites and URI resources.](./images/xias_users_add_006.png) - -1. Once the guest XIAS account has been created, the guest will need to login at and follow the automated [Cheaha Account Creation Process](../cheaha_account.md#creating-a-new-account) to create a Cheaha account. They will need to use the same email and password they used when creating their XIAS account. - -## Discovering and Managing Users - -There are two ways to discover XIAS users you are currently sponsoring. -The first is to search by email address. The second is to list all users -associated with a site. - -### Discovering Users - -1. To locate users by e-mail address: type their email into the "Locate specific user(s) by e-mail address" text field on the "Manage Users" page. - - ![!UAB XIAS User Management Webpage. An email search has been performed using the text field and a table listing names and emails is present at the top of the page.](./images/xias_users_list_000.png) - -1. To manage users by site: select the site from the drop-down box and click the "List" button. The page will reload with a table containing name, email, and start and end dates. The end date is when the XIAS user registration expires. To change the end date for user(s), click the "Sel" checkbox next to their names, enter a date in the "Change end date for selected users to" text field, and click "Update". - - ![!UAB XIAS User Management Webpage. A site listing has been performed using the site selection drop-down box and list button. A table of names, emails, start and end dates is present at the top of the page, along with checkboxes for changing end dates.](./images/xias_users_list_001.png) - -### Revoking User Privileges - - -!!! warning - - THIS INFORMATION IS PENDING TESTING - - -Users cannot have their XIAS account deleted. However, privileges may be revoked. To revoke user privileges, follow the instructions for managing users by site. Update the desired user(s)' end date to a date earlier than the current date. - - -!!! important - - If you need to urgently revoke privileges, please also notify UAB IT by emailing as soon as possible. Please be clear about what is needed and when. - diff --git a/docs/account_management/xias/pi_site_management.md b/docs/account_management/xias/pi_site_management.md deleted file mode 100644 index c3c2dea88..000000000 --- a/docs/account_management/xias/pi_site_management.md +++ /dev/null @@ -1,40 +0,0 @@ -# Creating a UAB XIAS Project/Site - - -!!! note - - These instructions are intended for use by UAB-employed PIs to organize external collaborators, also known as guests. UAB PIs: Please direct guests [here](guest_instructions.md) for instructions on creating their accounts. - - -XIAS Project/Sites, or simply sites, tie external users to specific resources at UAB. By connecting people to the resource they use, UAB can maintain security and accountability. Creating a site is the first step to giving access to external collaborators, and the process can be thought of as "create once, use many times". All sites must have an expiration date for security reasons. To create a site you'll need at least one Uniform Resource Identifier (URI) relating to resources used by the site. If you aren't sure what URI(s) to list for your site, please contact . - -1. To start go to the [UAB XIAS Project/Site Management Webpage](https://idm.uab.edu/cgi-cas/xrmi/sites). - - ![!UAB XIAS Project/Site Management Webpage with Manage Projects/Sites selected and a New button available.](./images/xias_sites_add_000.png) - -1. Click "New" to open a form for creating a new Project/Site. - - ![!Empty UAB XIAS Project/Site creation form with several fields.](./images/xias_sites_add_001.png) - -1. Fill in the form. All fields are required. - - 1. **Short name for project/site** - A memorable name for your project or site. - 1. **Longer description** - A complete yet concise description of the project or site and its resources. - 1. **Start date** - The start date, can be today. - 1. **End date** - An expiration date for the project or site. - 1. **URIs** - One or more uniform resource identifier (URIs) associated with the site, to increase accountability. - - 1. Cheaha URI: `https://rc.uab.edu` - 1. Cloud.rc URI: `https://cloud.rc.uab.edu` - 1. GitLab (code.rc) URI: `https://code.rc.uab.edu` - 1. Long-Term Storage (LTS) URI: `https://s3.lts.rc.uab.edu` - - ![!Filled UAB XIAS Project/Site creation form.](./images/xias_sites_add_002.png) - -1. Click "Add" to submit the form. You should be taken to a page summarizing the created Project/Site. - - ![!Summary page for created site reflecting user entered information.](./images/xias_sites_add_003.png) - -1. When you visit the "Manage Projects/Sites" page in the future, you will see a table with the newly created Project/Site listed. Click "View" to return to the page seen in the previous step. Click "Edit" to return to the form from \[link\]. Click "Users" to manage users for this site. - - ![!Site table with newly created site listed. On that row are three buttons: View, Edit, Users. On the next row is the button New.](./images/xias_sites_add_004.png) diff --git a/docs/cheaha/getting_started.md b/docs/cheaha/getting_started.md index 6bde1bf0d..bf26d1bdc 100644 --- a/docs/cheaha/getting_started.md +++ b/docs/cheaha/getting_started.md @@ -4,7 +4,23 @@ toc_depth: 3 # Getting Started -Cheaha is a High Performance Computing (HPC) resource intended primarily for batch processing of research computing software. We offer a user-friendly portal website Open OnDemand with graphical interfaces to the most common features, all in one place. Read on to learn more about our resources and how to access them. +Cheaha is the batch compute cluster platform of the Research Computing System (RCS). Cheaha is intended primarily for batch processing of research computing software. We offer a user-friendly portal website Open OnDemand with graphical interfaces to the most common features, all in one place. Read on to learn more about our resources and how to access them. + +Cheaha is appropriate for the following types of workflows: + +- High Performance Computing (HPC) +- High Throughput Computing (HTC) +- Batch Computing +- Graphical User Interface (GUI) and other interactive software + +Please bear in mind the following expectations when using Cheaha. + +- Resources are shared by many researchers. +- Jobs may take time to start. +- Jobs, partitions, and researchers all have caps on total resources in use at any one time. +- All jobs have a maximum time limit. + +If your needs go beyond these expectations, please [Contact Support](../help/support.md). ## What if I Need Help? @@ -12,11 +28,11 @@ Please [Contact Us](../index.md#how-to-contact-us) with requests for support. Pl ## Account Creation -Please visit our [Account Creation page](../account_management/cheaha_account.md) for detailed instructions on creating a Cheaha account. +Please visit our [Account Creation page](../account/rcs/create.md) for detailed instructions on creating a Cheaha account. ## Accessing Cheaha -The primary method for accessing Cheaha is through our online portal website, Open OnDemand. To login to our portal, navigate to our , which does not require an on-campus connection nor the UAB Campus VPN. You should be presented with UAB's Single Sign-on page, which will require use of [Duo 2FA](https://www.uab.edu/it/home/security/2-factor). Login using the appropriate credentials laid out at our [Account Creation page](../account_management/cheaha_account.md). +The primary method for accessing Cheaha is through our online portal website, Open OnDemand. To login to our portal, navigate to our , which does not require an on-campus connection nor the UAB Campus VPN. You should be presented with UAB's Single Sign-on page, which will require use of [Duo 2FA](https://www.uab.edu/it/home/security/2-factor). Login using the appropriate credentials laid out at our [Account Creation page](../account/rcs/create.md). [SSH](../uab_cloud/remote_access.md#command-line-via-ssh) may be used to access Cheaha. Connect to host `cheaha.rc.uab.edu` on port `22`. @@ -51,7 +67,7 @@ A full list of the available hardware can be found on our [hardware page](./hard ### Storage -All researchers are granted 5 TB of individual storage when they [create their Research Computing account](../account_management/cheaha_account.md). +All researchers are granted 5 TB of individual storage when they [create their Research Computing account](../account/rcs/create.md). Shared storage is available to all Lab Groups and Core Facilities on campus. Shared storage is also available to UAB Administration groups. @@ -61,13 +77,13 @@ Please visit our [Storage page](../data_management/index.md) for detailed inform Compute nodes are divided into groups called partitions each with specific qualities suitable for different kinds of workflows or software. In order to submit a compute job, a partition must be chosen in the Slurm options. The partitions can be roughly grouped as such: -| Use | Partition Names | Notes | -|---|---|---| -| GPU Processing | pascalnodes, pascalnodes-medium, amperenodes, amperenodes-medium | These are the only partitions with GPUs | -| All Purpose | amd-hdr100 | Runs AMD CPUs compared to all other CPU partitions running Intel. [Contact us](../index.md#how-to-contact-us) with issues running on this partition | -| Shorter time | express, short, intel-dcb | | -| Medium-long time | medium, long | | -| Very large memory | largemem, largemem-long | | +| Use | Partition Names | Notes | +|-------------------|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| GPU Processing | pascalnodes, pascalnodes-medium, amperenodes, amperenodes-medium | These are the only partitions with GPUs | +| All Purpose | amd-hdr100 | Runs AMD CPUs compared to all other CPU partitions running Intel. [Contact us](../index.md#how-to-contact-us) with issues running on this partition | +| Shorter time | express, short, intel-dcb | | +| Medium-long time | medium, long | | +| Very large memory | largemem, largemem-long | | Please visit our [hardware](hardware.md#cheaha-hpc-cluster) for more details about the partitions. @@ -182,3 +198,20 @@ For new software installation, please try searching [Anaconda](../workflow_solut A significant amount of open-source software is distributed as Anaconda or Python libraries. These libraries can be installed by the user without permission from Research Computing using Anaconda environments. To read more about using Anaconda virtual environments see our [Anaconda page](./software/software.md#anaconda-on-cheaha). If the software installation instructions tell you to use either `conda install` or `pip install` commands, the software and its dependencies can be installed using a virtual environment. + +## Frequently Asked Questions + +- **What should I do to access shared storages and recognize my group membership after being added to a group on Cheaha?** + + - **Do you have any processes/connections on `cheaha.rc.uab.edu`**? + + - Please exit and log back in. + - If you have active Tmux/Screen sessions, you will need to terminate those as well, log out, log back in and start Tmux. + + - **Do you have an active Open OnDemand session?** + + - In Open OnDemand (), navigate to the green navigation bar in the top right corner. Look for the `Help` or `Developer` dropdown menu and click on it. Then, click `Restart Web Server`. Once the restart is complete, please try again. + + - **Do you have one or more OOD HPC Desktops running?** + + - Terminate the desktops and start new ones. diff --git a/docs/cheaha/slurm/practical_sbatch.md b/docs/cheaha/slurm/practical_sbatch.md index 09d368e9b..cdb145d27 100644 --- a/docs/cheaha/slurm/practical_sbatch.md +++ b/docs/cheaha/slurm/practical_sbatch.md @@ -169,7 +169,9 @@ shopt -s nullglob input_files=(../inputs/**/dice.csv) +{% raw %} FILE_COUNT=${#input_files[@]} +{% endraw %} FILE_COUNT=$(( $FILE_COUNT - 1 )) sbatch --array=0-$FILE_COUNT%4 job.sh @@ -181,7 +183,7 @@ sbatch --array=0-$FILE_COUNT%4 job.sh 1. The line `input_files=(../inputs/**/dice.csv)` uses the glob pattern `../inputs/**/dice.csv` to create a shell array of paths to files in our dataset. The details of this are discussed above in [File Extraction](#file-extraction). -1. The line `FILE_COUNT=${#input_files[@]}` gets all entries from the `input_files` array using the special index `@` (for all elements), then counting them with the prefix symbol `#`. +1. The line {% raw %}`FILE_COUNT=${#input_files[@]}`{% endraw %} gets all entries from the `input_files` array using the special index `@` (for all elements), then counting them with the prefix symbol `#`. !!! tip @@ -264,7 +266,9 @@ shopt -s nullglob input_files=(../inputs/**/dice.csv) +{% raw %} FILE_COUNT=${#input_files[@]} +{% endraw %} FILE_COUNT=$(( $FILE_COUNT - 1 )) sbatch --array=0-$FILE_COUNT%4 job.sh diff --git a/docs/account_management/images/uab-gitlab-creategrp.png b/docs/code.rc/_img/uab-gitlab-creategrp.png similarity index 100% rename from docs/account_management/images/uab-gitlab-creategrp.png rename to docs/code.rc/_img/uab-gitlab-creategrp.png diff --git a/docs/account_management/images/uab-gitlab-creategrp2.png b/docs/code.rc/_img/uab-gitlab-creategrp2.png similarity index 100% rename from docs/account_management/images/uab-gitlab-creategrp2.png rename to docs/code.rc/_img/uab-gitlab-creategrp2.png diff --git a/docs/account_management/images/uab-gitlab-createproject.png b/docs/code.rc/_img/uab-gitlab-createproject.png similarity index 100% rename from docs/account_management/images/uab-gitlab-createproject.png rename to docs/code.rc/_img/uab-gitlab-createproject.png diff --git a/docs/account_management/images/uab-gitlab-createproject2.png b/docs/code.rc/_img/uab-gitlab-createproject2.png similarity index 100% rename from docs/account_management/images/uab-gitlab-createproject2.png rename to docs/code.rc/_img/uab-gitlab-createproject2.png diff --git a/docs/account_management/images/uab-gitlab-domaindiff.png b/docs/code.rc/_img/uab-gitlab-domaindiff.png similarity index 100% rename from docs/account_management/images/uab-gitlab-domaindiff.png rename to docs/code.rc/_img/uab-gitlab-domaindiff.png diff --git a/docs/account_management/images/uab-gitlab-group1.png b/docs/code.rc/_img/uab-gitlab-group1.png similarity index 100% rename from docs/account_management/images/uab-gitlab-group1.png rename to docs/code.rc/_img/uab-gitlab-group1.png diff --git a/docs/account_management/images/uab-gitlab-group2.png b/docs/code.rc/_img/uab-gitlab-group2.png similarity index 100% rename from docs/account_management/images/uab-gitlab-group2.png rename to docs/code.rc/_img/uab-gitlab-group2.png diff --git a/docs/account_management/images/uab-gitlab-grouptest.png b/docs/code.rc/_img/uab-gitlab-grouptest.png similarity index 100% rename from docs/account_management/images/uab-gitlab-grouptest.png rename to docs/code.rc/_img/uab-gitlab-grouptest.png diff --git a/docs/account_management/images/uab-gitlab-grplist.png b/docs/code.rc/_img/uab-gitlab-grplist.png similarity index 100% rename from docs/account_management/images/uab-gitlab-grplist.png rename to docs/code.rc/_img/uab-gitlab-grplist.png diff --git a/docs/account_management/images/uab-gitlab-grpmembers.png b/docs/code.rc/_img/uab-gitlab-grpmembers.png similarity index 100% rename from docs/account_management/images/uab-gitlab-grpmembers.png rename to docs/code.rc/_img/uab-gitlab-grpmembers.png diff --git a/docs/account_management/images/uab-gitlab-invitemembers.png b/docs/code.rc/_img/uab-gitlab-invitemembers.png similarity index 100% rename from docs/account_management/images/uab-gitlab-invitemembers.png rename to docs/code.rc/_img/uab-gitlab-invitemembers.png diff --git a/docs/account_management/images/uab-gitlab-invitemembers2.png b/docs/code.rc/_img/uab-gitlab-invitemembers2.png similarity index 100% rename from docs/account_management/images/uab-gitlab-invitemembers2.png rename to docs/code.rc/_img/uab-gitlab-invitemembers2.png diff --git a/docs/account_management/images/uab-gitlab-invitemembers3.png b/docs/code.rc/_img/uab-gitlab-invitemembers3.png similarity index 100% rename from docs/account_management/images/uab-gitlab-invitemembers3.png rename to docs/code.rc/_img/uab-gitlab-invitemembers3.png diff --git a/docs/account_management/images/uab-gitlab-landingpage.png b/docs/code.rc/_img/uab-gitlab-landingpage.png similarity index 100% rename from docs/account_management/images/uab-gitlab-landingpage.png rename to docs/code.rc/_img/uab-gitlab-landingpage.png diff --git a/docs/account_management/images/uab-gitlab-projectgroup.png b/docs/code.rc/_img/uab-gitlab-projectgroup.png similarity index 100% rename from docs/account_management/images/uab-gitlab-projectgroup.png rename to docs/code.rc/_img/uab-gitlab-projectgroup.png diff --git a/docs/account_management/images/uab-gitlab-projectlist.png b/docs/code.rc/_img/uab-gitlab-projectlist.png similarity index 100% rename from docs/account_management/images/uab-gitlab-projectlist.png rename to docs/code.rc/_img/uab-gitlab-projectlist.png diff --git a/docs/account_management/images/uab-gitlab-updaterole.png b/docs/code.rc/_img/uab-gitlab-updaterole.png similarity index 100% rename from docs/account_management/images/uab-gitlab-updaterole.png rename to docs/code.rc/_img/uab-gitlab-updaterole.png diff --git a/docs/account_management/res/gitlab_roles.csv b/docs/code.rc/_res/gitlab_roles.csv similarity index 100% rename from docs/account_management/res/gitlab_roles.csv rename to docs/code.rc/_res/gitlab_roles.csv diff --git a/docs/code.rc/index.md b/docs/code.rc/index.md new file mode 100644 index 000000000..fb52ab9a2 --- /dev/null +++ b/docs/code.rc/index.md @@ -0,0 +1,160 @@ +# Code.rc (GitLab) + +## What Is Code.rc? + +**Code.rc** is the Research Computing System (RCS) on-premises GitLab server. + +## Why Use Code.rc? + +Code.rc has features supporting: + +- Accountability + - Track who is responsible for what aspects of project work. + - Issue tracking and deadlines. + - Calendars. + - Project organization via Groups. +- Collaboration + - Issue tracking with discussions, due dates, cross-linking, and kanban boards. + - Access control via Roles and Groups. + - Automation via continuous integration and continuous deployment (CI/CD). + - Organize workflows among multiple collaborators. + - Wiki pages. +- Reproducibility + - Code and project definitions can be kept in a single, central repository + - The repository serves as a reference for other researchers. + - Code changes are tracked as a project evolves. +- Security + - Hosted at UAB Campus. + - Requires UAB Campus credentials to access. + +## What Are Groups, Projects, and Roles? + +Managing roles and user permissions within GitLab is essential for maintaining control over repositories and collaboration. Within GitLab, a user (Owner) can assign and update user roles in a group. There are several roles for users within GitLab, and these roles determine the level of permissions a user will have within a Group or project. In GitLab, permissions are organized in a hierarchical group/project tree structure. At the top is a Group, which can contain subgroups and individual projects. This structure makes permission control easy to manage. Groups can represent schools, faculty, departments, labs or cores, while projects hold the actual code, issues, and CI/CD configurations for grants and research they administer. + +The available default roles within a group/project are listed in the table; + +{{ read_csv('_res/gitlab_roles.csv', keep_default_na=False) }} + +A user assigned the "Guest" role has the least permissions, and the "Owner" has the most permissions. The table summarizes key features and permissions per user role in a Group/Project. For a complete list of permissions each role can perform, please see [GitLab documentation for user permissions](https://docs.gitlab.com/user/permissions/). In the section [Assigning a User's GitLab Role](#how-do-i-assign-gitlab-roles), you will see a guide to create, and assign user roles within your GitLab project. + +## Why Are Groups, Projects, and Roles Important? + +GitLab’s Group and Project structure offers a powerful way to mirror how your research lab or programs are structured. When we consider the organizational setup at UAB, where a Core oversees several specialized Labs. Each lab is led by a different PI, researcher or department. Within each Lab, multiple projects are being run, possibly by different teams, postdocs, or students. GitLab’s inheritance Group to Project model, shows Groups can contain subgroups and projects, making it possible to organize this exact structure digitally (Core->Lab/Department->Projects). The Core entity at UAB can be represented as a top-level group, each Lab as a subgroup, and individual projects (e.g., datasets, analysis pipelines, or software tools) as repositories within those subgroups. + +This structure helps to maintain a clear navigation system, it also ensures efficient role and permission management. The Core can assign high-level oversight roles at the Group level, while Labs can manage their own subgroups independently. Developers and researchers can be granted access only to the projects they work on, without exposing unrelated projects or sensitive data they should not have access to, adhering to the principle of least privilege. Combined with GitLab’s role inheritance and ability to override roles at lower levels, this design promotes scalability, security, and accountability, while supporting collaborative research across a complex institutional environment like UAB. + +## How Do I Assign GitLab Roles? + +In GitLab, only a user with the role "Owner" can assign or change a GitLab role for a user across "Projects" or "Groups". Whereas, a "Maintainer" has project-level privileges and can only manage users that are part of a "Project" within a "Group", the "Owner" has group-wide privileges that extend to the "Projects" under their "Group". Remember, for a User to be added to a Group, they would need to have a Code.rc account set up. Please see the [Code.rc Account Creation](../account/code.rc/create.md) page for setting one up. + +The following instructions are to guide you in creating a group and/or assigning user roles as a group owner. + +### Creating a GitLab Group + +1. Log in to [Code.rc](https://code.rc.uab.edu/users/sign_in) using your UAB Credentials. + + ![!image showing UAB RC GitLab Landing Page](_img/uab-gitlab-landingpage.png) + +1. Click on the "Groups" menu option. + + ![!image showing Logged-in interface](_img/uab-gitlab-group1.png) + +1. Select "New group". + + ![!image showing Groups a user has access to on GitLab, with the New group button highlighted](_img/uab-gitlab-group2.png) + +1. Now select the "Create group" option. You may select the "Import group" option, if you have projects and their associated data from other Git hosting services. For this guide, we are assuming this is not the case, and you are setting up a new Group. + + ![!image showing the Create group and Import group option, with the Create group option highlighted](_img/uab-gitlab-creategrp.png) + +1. Fill out the form to create your group, make sure to include a name, and appropriate "Visibility level". There are three (3) levels for visibility, pick the option meeting your needs. Click on the "Create group" option, and this completes the Group creation process. + + ![!image showing the form to Create group, with the Group name, Visibility level and Create group options highlighted](_img/uab-gitlab-creategrp2.png) + + + !!! note + + GitLab allows you to define Group visibility using "Public", "Internal", or "Private" settings. A public Group is visible to and can be cloned by anyone, even without a Code.rc account. An internal Group is visible to any authenticated Code.rc user, but access to contribute is still controlled by roles. A private Group is only visible and accessible to users who have been explicitly granted access. These settings work in tandem with permissions to control both who sees what and what they can do in a Group. See [GitLab documentation](https://docs.gitlab.com/user/public_access/) for more information. + + +1. Now that your group has been created, we can [add users with varying roles](#add-and-assign-user-roles-within-a-group-or-project) that grant different user permissions. + + ![!image showing a list of Groups](_img/uab-gitlab-grplist.png) + +### Creating a GitLab Project + +As a Maintainer or Owner you can create Projects from within a Group. Steps 1 and 2 are same as the instructions for [Creating a Group](#creating-a-gitlab-group), there is a slight deviation at the third step. + +1. Log in to [Code.rc](https://code.rc.uab.edu/users/sign_in) using your UAB Credentials. + + ![!image showing UAB RC GitLab Landing Page](_img/uab-gitlab-landingpage.png) + +1. Click on the "Groups" menu option. And select the appropriate Group. + + ![!image showing Logged-in interface](_img/uab-gitlab-grouptest.png) + +1. From within the group, Select "New project". + + ![!image showing Groups a user has access to on GitLab, with the New group button highlighted](_img/uab-gitlab-projectgroup.png) + +1. Now select from one of the options to create new project, in this example we use the "Create blank project" option. You may select the "Import project" option, or "Create from template" option. For this guide, we are assuming this is not the case, and you are setting up a new Project. + + ![!image showing the Create new Project options, with the Create group option highlighted](_img/uab-gitlab-createproject.png) + +1. Fill out the form to create your Project, make sure to include a name, and appropriate "Visibility level". There are three (3) levels for visibility, pick the option meeting your needs. Click on the "Create project" option, and this completes the Project creation process. + + ![!image showing the form to Create project, with the Project name, Visibility level and Create project options highlighted](_img/uab-gitlab-createproject2.png) + + + !!! note + + GitLab allows you to define project visibility using "Public", "Internal", or "Private" settings like in a group. A public project is visible to and can be cloned by anyone, even without a Code.rc account. An internal project is visible to any authenticated Code.rc user, but access to contribute is still controlled by roles. A private project is only visible and accessible to users who have been explicitly granted access. These settings work in tandem with role-based permissions that control who can see what and what they can do in a project. See [GitLab documentation](https://docs.gitlab.com/user/public_access/) for more information. + + +1. Now that your project has been created, we can [add users with varying roles](#add-and-assign-user-roles-within-a-group-or-project) that grant different user permissions. To see members in your project, select the "Manage" option and then select the "Members" option. This will take you to the list of members who are part of that project. + + ![!image showing the list of Members in a Project](_img/uab-gitlab-projectlist.png) + +### Add and Assign User Roles Within a Group or Project + +1. Click on the Group/Project, you have requisite permissions to (Owner for Groups, Owner or Maintainer for Projects). From within your Group/Project, click on the "Manage" pane located to the left of your Group/Project. And then click on "Invite members". If you are already part of another Group, dependent on the permissions you have in those Groups, you may be able to add all members of a Group with the "Invite a group" option, but for this guide, we are focusing on the "Invite members" option. + + ![!image showing Members list of a Group in GitLab, with the "Manage", "Members", "Invite a group" and "Invite members" options highlighted](_img/uab-gitlab-invitemembers.png) + + + !!! note + + Please note, GitLab follows a "Group to Project" inheritance model, where a user added to a Group, would inherit that same role, when a new Project is created unless that role is changed. For instance, a user maybe assigned a Guest role at the Group level, but may have a higher role assigned at the project level. + + +1. The "Invite members" option, would open up to a mini window that shows an interface to invite members with their "Username, name or email address", an option to "Select a role", an option that allows you to set "Access expiration date" for a user, and the "Invite" button. + + ![!image showing options from selecting "Invite members"](_img/uab-gitlab-invitemembers2.png) + + The option "Select a role" is where you select what kind of role, you want the listed user(s) to have. Please refer to the [Groups, Projects, and Roles section](#what-are-groups-projects-and-roles) to see what each user role has permissions to do within your Group/Project. + + ![!image showing Roles available from the "Select a role" option](_img/uab-gitlab-invitemembers3.png) + + + !!! note + + You can only add uab.edu entities or domain emails to Code.rc, you will get an error like in the image below if you do otherwise. Please see our page on [Code.rc Registration](../account/code.rc/create.md) to address adding external collaborators before attempting the prior steps. + + ![!image showing error from adding non-UAB email or entities](_img/uab-gitlab-domaindiff.png) + + +1. Now you can see a list of Group/Project members, showing their "Account" i.e. their Name and BlazerID, their "Source" i.e. how they joined the group, their "Role" i.e. level of permission within your Group, and "Expiration" i.e. how long they will have access to the group, unless this is changed, the default option is for a user to have access indefinitely. In this guide, one of the user's has an expiration of `2025-04-14`, after this date the user will no longer have access to your Group/Project. In the last column we have "Activity" i.e. additional metadata for the user. + + ![!image showing members in a Group](_img/uab-gitlab-grpmembers.png) + + You can also remove a user from your Group/Project, by clicking on the "More actions" button, the three (3) vertical lines to the right of an Account, and click the "Remove member" option. + + + !!! note + + To manage security risks please apply the principle of Least Privilege when assigning roles. The principle states that users should be given the minimum level access to perform their roles. This is to mitigate security risks and operational errors. This principle ensures you limit members of your Group who can intentionally or unintentionally make destructive or irrevocable changes. + + +1. You can also change or update a user's role, by selecting one of the other options provided under the "Role" column for an Account. This changes the user's role within the Group/Project. + + ![!image showing roles a member can be changed to or updated to in a Group](_img/uab-gitlab-updaterole.png) diff --git a/docs/data_management/code_storage.md b/docs/data_management/code_storage.md index f839f5f13..d9e6a53cd 100644 --- a/docs/data_management/code_storage.md +++ b/docs/data_management/code_storage.md @@ -4,11 +4,11 @@ Unlike with traditional raw data storage, code evolves over time, often rapidly. ## UAB GitLab vs the Third-Party GitHub: Which Should I Choose? -If your work is private, or internal to UAB operations, it is probably best to store it in our [GitLab](#gitlab) instance, hosted on-premises as UAB. In contrast, if you must collaborate with external researchers, it might make more sense to store code in [GitHub](#github), instead. GitLab has more feature-rich project management tooling in support of code collaboration, but GitHub is more widely known, recognized and can more readily travel with you as you progress in your career. +If your work is private, or internal to UAB operations, it is probably best to store it in our [Code.rc](../account/code.rc/index.md) server, hosted on-premises as UAB. In contrast, if you must collaborate with external researchers, it might make more sense to store code in [GitHub](#github), instead. GitLab has more feature-rich project management tooling in support of code collaboration, but GitHub is more widely known, recognized and can more readily travel with you as you progress in your career. ### GitLab -UAB Research Computing maintains an on-premises GitLab instance. To gain access, please visit and create an [Account](../account_management/gitlab_account.md). +UAB Research Computing maintains an on-premises GitLab server called Code.rc. To gain access, please create a [Code.rc Account](../account/code.rc/create.md). ### GitHub diff --git a/docs/data_management/index.md b/docs/data_management/index.md index f66b3a22f..2a02888db 100644 --- a/docs/data_management/index.md +++ b/docs/data_management/index.md @@ -78,7 +78,7 @@ To request shared Project Storage or Long-Term Storage, please contact [Support] - Requests must come from one of the proposed owners (a Lab PI, a Research Core director, or both). - The role of Lab PI entitles a person to a project space for that lab. - The role of Research Core director entitles a person to a project space for that core. If one person has both roles, they may have two shared Storage spaces, one for each role. -- All proposed owners must have created their [Research Computing accounts](../account_management/cheaha_account.md) at the time of the request. +- All proposed owners must have created their [Research Computing accounts](../account/rcs/create.md) at the time of the request. Please provide the following information. Missing information can delay allocation of Shared Storage as we either look up the information, or ask followup questions. diff --git a/docs/data_management/lts/iam_and_policies.md b/docs/data_management/lts/iam_and_policies.md index 7dcbf2c26..4f9577945 100644 --- a/docs/data_management/lts/iam_and_policies.md +++ b/docs/data_management/lts/iam_and_policies.md @@ -46,7 +46,7 @@ IAM Names are case-sensitive identifiers for allocations and allow granting othe ## Individual LTS Allocations -Individual LTS allocations are intended for personal use and are available to all UAB affiliated individuals and their external collaborators (via a [XIAS account](../../account_management/xias/index.md)). These allocations are tied to the individual’s primary UAB email and provide 5 TB of storage. +Individual LTS allocations are intended for personal use and are available to all UAB affiliated individuals and their external collaborators (via a [XIAS account](../../account/xias/index.md)). These allocations are tied to the individual’s primary UAB email and provide 5 TB of storage. We recommend following the [Individual LTS Tutorial](./tutorial/individual_lts_tutorial.md) to familiarize yourself with working with LTS at the command line. diff --git a/docs/data_management/lts/index.md b/docs/data_management/lts/index.md index 0c18e6911..fcc7882c2 100644 --- a/docs/data_management/lts/index.md +++ b/docs/data_management/lts/index.md @@ -49,4 +49,4 @@ Better practice when naming buckets is to use a short, descriptive and memorable ## What to Do With Data When I Leave UAB? -See our [Leaving UAB page](../../account_management/leaving_uab.md). +See our [Leaving UAB page](../../account/leaving/index.md). diff --git a/docs/data_management/transfer/tutorial/globus_individual_tutorial.md b/docs/data_management/transfer/tutorial/globus_individual_tutorial.md index bcc7f2a86..18393378b 100644 --- a/docs/data_management/transfer/tutorial/globus_individual_tutorial.md +++ b/docs/data_management/transfer/tutorial/globus_individual_tutorial.md @@ -41,7 +41,7 @@ Globus is an ecosystem of software intended to make research data transfer simpl ## Tutorial Prerequisites -For these tutorials, you will need your BlazerID or [XIAS ID](../../../account_management/xias/index.md) and password to authenticate using UAB Single Sign-On (SSO). +For these tutorials, you will need your BlazerID or [XIAS ID](../../../account/xias/index.md) and password to authenticate using UAB Single Sign-On (SSO). ## How Do I Get Onto the Globus Web App? @@ -54,7 +54,7 @@ For these tutorials, you will need your BlazerID or [XIAS ID](../../../account_m !!! note - If you are an external collaborator using a [XIAS account](../../../account_management/xias/index.md) (this is uncommon) to interact with UAB-owned storage you will still need to search for "UAB". Do not use your home institution login to access UAB storage systems, as you will only have access to UAB storage with your XIAS credentials. + If you are an external collaborator using a [XIAS account](../../../account/xias/index.md) (this is uncommon) to interact with UAB-owned storage you will still need to search for "UAB". Do not use your home institution login to access UAB storage systems, as you will only have access to UAB storage with your XIAS credentials. ![Globus Web App login search bar with UAB entered and University of Alabama at Birmingham in a red box.](./images/gi-web-app/002-search.png) diff --git a/docs/data_management/transfer/tutorial/globus_organization_tutorial.md b/docs/data_management/transfer/tutorial/globus_organization_tutorial.md index b290c62d3..4d2cd66df 100644 --- a/docs/data_management/transfer/tutorial/globus_organization_tutorial.md +++ b/docs/data_management/transfer/tutorial/globus_organization_tutorial.md @@ -40,7 +40,7 @@ Globus is an ecosystem of software intended to make research data transfer simpl ## Tutorial Prerequisites -For these tutorials, you will need your BlazerID or [XIAS ID](../../../account_management/xias/index.md) and password to authenticate using UAB Single Sign-On (SSO). +For these tutorials, you will need your BlazerID or [XIAS ID](../../../account/xias/index.md) and password to authenticate using UAB Single Sign-On (SSO). ## How Do I Get Onto the Globus Web App? diff --git a/docs/help/support.md b/docs/help/support.md index 6c5bc0743..aea6e7508 100644 --- a/docs/help/support.md +++ b/docs/help/support.md @@ -1,9 +1,13 @@ # How to Request Support +{% import "_macro/support.md.j2" as sp with context %} + Before reaching out to us, try searching this documentation for keywords related to your issue. If you aren't able to find anything, please try checking our FAQ located on [ask.cyberinfrastructure](https://ask.cyberinfrastructure.org/c/locales-data-centers-and-campus-rc/uab/52). If you still need help, please read on for how to send in a ticket and how to work with our ticketing system. ## How Do I Create a Support Ticket? +{{ sp.support_card_email() }} + To Create a support ticket, send a descriptive email to to create a ticket. Bonus points for including the following details. For general issues: @@ -70,6 +74,8 @@ Please do not try to attach executable files to tickets. If you have a legitimat ## How Can I Follow Up on ServiceNow Tickets? +{{ sp.support_card_servicenow() }} + If you are unable to find a reference or correspondence for your already submitted ServcieNow ticket, you can now visit UAB's [ServiceNow portal](https://uabprod.service-now.com/service_portal) to track and follow up your submitted tickets. At the website, click the "Log in" button to sign in with your UAB SSO (Single Sign On) credentials. ![Landing page of ServiceNow Portal with the "Log in" button highlighted](images/servicenow_landing_page.png) @@ -92,12 +98,8 @@ If you are not able to find a suitable module or package and would like software ## Office Hours -For our office hours links please see [Contact Us](../index.md#how-to-contact-us). +{{ sp.support_card_office_hours() }} ## Status Updates -For status updates affecting our systems or services please visit . - -At this page you can subscribe to notifications using the bell icon next to the name "Research Computing" near the top-left of the page. - -![!subscribe button on status update page](images/support_status_update_subscribe.png) +{{ sp.support_card_statuscast() }} diff --git a/docs/index.md b/docs/index.md index 4ef167124..7fd55b2aa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,19 +2,54 @@ The Research Computing System (RCS) provides a framework for sharing research data, accessing computing power, and collaborating with peers on campus and around the globe. We have deployed a dynamic "network of services" to facilitate organizing, studying, and sharing research data. -## News +## Announcements -!!! announcement - - Research Computing will be performing a data migration for Cheaha beginning Saturday, October 11 and lasting through the end of the month. Please see our [migration overview](./news/posts/2025-10-07-migration-overview.md) for more information on what to expect during this time. + +{% if announcements %} +{% for announcement in announcements %} +???+ announcement "Announcement: {{ announcement.title }}" + {{ announcement.content | indent(4) }} +
+
+
+ **Effective:** + {%- if announcement.start_date %} + {{ announcement.start_date }} + {% endif -%} + {%- if announcement.start_date and announcement.end_date -%} + — + {%- endif -%} + {%- if announcement.end_date %} + {{ announcement.end_date }} + {% endif -%} +
+
+ _Posted: {{ announcement.posted_date }}_ +
+
+{% else %} + {{ no_announcements }} +{% endfor %} +{% else %} + {{ no_announcements }} +{% endif %} + -**Check our [News page](./news/index.md) for recent developments.** - ## How Do I Get Started? -Create [your Cheaha Account](./account_management/cheaha_account.md), then check out our [Featured Tutorials](#featured-tutorials) below. If you have a specific goal in mind, try searching our documentation, or see our [Success Stories](#success-stories) for inspiration on what we can do. Represent an internal organization and want to start a collaboration? See our [Outreach](#outreach) section. If you still can't find what you need, please [Contact Us](#how-to-contact-us). +{{ + renderer.render_cards( + cards.news, + cards.account.rcs.create, + cards.platforms.cheaha.ood.overview, + cards.platforms.cheaha.slurm.overview, + cards.data.individual_storage, + cards.data.shared_storage, + cards.data.transfer_options, + ) +}} ### Featured Tutorials @@ -56,17 +91,13 @@ If you would like to build a collaborative effort with Research Computing, pleas ## How to Contact Us -Please reach out to us via email at to create a support ticket. - -For face-to-face support please visit us in our Zoom office hours held weekly: - -- Mondays 10:00 AM to 12:00 PM: -[Zoom](https://uab.zoom.us/j/81783104592?pwd=L21OOWNlY2doWXova3MzOGFRcE4zQT09) - -- Thursdays 10:00 AM to 12:00 PM: -[Zoom](https://uab.zoom.us/j/81783104592?pwd=L21OOWNlY2doWXova3MzOGFRcE4zQT09) - -For additional information please see our [Support Page](./help/support.md). +{{ + renderer.render_cards( + cards.support.email, + cards.support.office_hours, + cards.support.page, + ) +}} ## About Us diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 936157f3d..a414b39cc 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,6 +1,12 @@ -/* UAB theming */ +/* +DEFINITIONS FOR THEMING +*/ :root { - /* uab colors in approximate order of prioritization */ + /* + UAB COLORS in approximate order of prioritization. + Note most colors are not WCAG compliant on white backgrounds. + "dragons-lair-green" may be indistinguishable from black on a white background. + */ --uab-color-uab-green: #1a5632; --uab-color-uab-gold: #fdb913; --uab-color-dragons-lair-green: #033319; @@ -8,91 +14,196 @@ --uab-color-ever-loyal-green: #17b045; --uab-color-bham-sky-blue: #42caf0; - /* uab color usage */ + /* MKDOCS MATERIAL COLOR overrides and definitions. */ --md-primary-fg-color: var(--uab-color-uab-green); --md-primary-fg-color--dark: var(--uab-color-uab-green); --announcement-admonition-bd-color: #90d408; --announcement-admonition-bg-color: color-mix(in srgb, var(--announcement-admonition-bd-color) 10%, transparent); - - /* other color usage */ --construction-admonition-bd-color: #eed202; --construction-admonition-bg-color: color-mix(in srgb, var(--construction-admonition-bd-color) 10%, transparent); + --important-admonition-bd-color: #ff9100; + --important-admonition-bg-color: color-mix(in srgb, var(--important-admonition-bd-color) 10%, transparent); + --security-admonition-bd-color: #ff1744; + --security-admonition-bg-color: color-mix(in srgb, var(--security-admonition-bd-color) 10%, transparent); + + /* OTHER COLORS */ --support-email-color: #aaaaff; --edit-page-icon-color: #5555ff; --lightbox-shadow-color: rgba(0, 0, 0, 0.08); + + /* ICONS */ + --md-admonition-icon--material-bullhorn: url('data:image/svg+xml;charset=utf-8,bullhorn'); + --md-admonition-icon--material-crane: url('data:image/svg+xml;charset=utf-8,crane'); + --md-admonition-icon--material-decagram-alert: url('data:image/svg+xml;charset=utf-8,alert-decagram'); + --md-admonition-icon--material-shield-alert: url('data:image/svg+xml;charset=utf-8,shield-alert'); } -/* logo fix */ +/* LOGO ADJUSTMENTS */ .md-header__button.md-logo :is(img, svg) { height: 1.2rem; width: auto !important; } -/* link color correction */ - -.md-content>:not(.md-sidebar) a, -.md-content>:not(.md-sidebar) a:visited { +/* LINK ADJUSTMENTS */ +/* link color and bottom border to ensure element shape consistency on hover */ +.md-content a { color: revert; + border-bottom: 1px solid; + border-color: rgba(0, 0, 0, 0) } -.md-content>:not(.md-sidebar) a:hover { - color: revert; - border-bottom: 1px solid; +/* visible bottom border only on hover */ +.md-content a:hover { + border-color: revert; } -.md-content a.headerlink:hover { +/* +remove bottom-border from special cases +- section anchor link icon +- images +- Edit this page on GitHub icon +*/ +.md-typeset .headerlink, +.md-content a.glightbox:has(img), +.md-content a.md-icon[title="Edit this page"] { border-bottom: none; } -html .md-footer-meta.md-typeset a.supportemail { +/* special case coloring for supportemail link due to dark background */ +.md-footer .md-copyright a.supportemail { color: var(--support-email-color); } -/* "Edit on GitHub" button color adjustment */ -.md-icon[title="Edit this page"] svg { - fill: var(--edit-page-icon-color); +/* HEADER ADJUSTMENTS */ +/* header style consistency */ +.md-typeset h1, +.md-typeset h2, +.md-typeset h3, +.md-typeset h4, +.md-typeset h5, +.md-typeset h6 { + color: var(--md-default-fg-color); + font-weight: 600; + line-height: normal; } -/* header accessiblity/readability */ +/* h1 adjustments */ .md-typeset h1 { - color: var(--md-default-fg-color); - font-weight: 600; font-size: 2em; + margin-bottom: 0; } -.md-typeset:not(.md-blog-header) h1 { - margin-bottom: 0; +/* adjust whitespace between h1 and immediate nested headers */ +.md-typeset h1+ :is(h2, h3, h4, h5, h6) { + margin-top: 0.8em; } -.md-typeset h2 { - font-weight: 600; - line-height: normal; +/* increase whitespace between last content of previous section and next header */ +.md-typeset :not(h1, h2, h3, h4, h5, h6)+ :is(h2, h3, h4, h5, h6) { + margin-top: 40px; } -.md-typeset h3 { - font-weight: 600; - line-height: normal; +/* LIST ADJUSTMENTS */ +/* ol, ul more compact */ +.md-typeset ol, +.md-typeset ul { + margin-bottom: revert; + margin-top: revert; } -.md-typeset h4 { - font-weight: 600; - line-height: normal; +.md-typeset ol li, +.md-typeset ol li>p, +.md-typeset ul li, +.md-typeset ul li>p { + margin-bottom: 0.0em; } -.md-typeset h5 { - font-weight: 600; - line-height: normal; - color: var(--md-default-fg-color); +.md-typeset ol li :nth-child(1), +.md-typeset ul li :nth-child(1) { + margin-top: 0.0em; } -.md-typeset :not(h1, h2, h3, h4, h5)+ :is(h2, h3, h4, h5) { - margin-top: 44px; +.md-typeset ol li :last-child:is(p), +.md-typeset ul li :last-child:is(p) { + margin-bottom: 0.0em; } -.md-typeset h1+ :is(h2, h3, h4) { - margin-top: 0.8em; +.md-typeset ol li ol, +.md-typeset ol li ul, +.md-typeset ul li ol, +.md-typeset ul li ul { + margin-bottom: 0.0em; + margin-top: 0.0em; +} + +/* NAV ADJUSTMENTS */ +.md-nav--primary .md-nav__item--active>.md-nav__link>a>span.md-ellipsis, +.md-nav--primary .md-nav__link--active>span.md-ellipsis { + font-weight: bold; +} + +/* CUSTOM ADMONITION DEFINITIONS*/ +/* announcement admonition */ +.md-typeset .admonition.announcement, +.md-typeset details.announcement { + border-color: var(--announcement-admonition-bd-color); +} + +.md-typeset .announcement>.admonition-title, +.md-typeset .announcement>summary { + background-color: var(--announcement-admonition-bg-color); + border-color: var(--announcement-admonition-bd-color); +} + +.md-typeset .announcement>.admonition-title::before, +.md-typeset .announcement>summary::before { + background-color: var(--announcement-admonition-bd-color); + -webkit-mask-image: var(--md-admonition-icon--material-bullhorn); + mask-image: var(--md-admonition-icon--material-bullhorn); } + +.md-typeset details.announcement { + font-size: 0.8rem; +} + +.md-typeset details.announcement summary { + font-size: 1.25em; + padding-left: 2.5em; + padding-right: 2.5em; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.md-typeset details.announcement summary::before, +.md-typeset details.announcement summary::after { + height: 1.25em; + width: 1.25em; +} + +.md-typeset details.announcement p, +.md-typeset details.announcement hr { + margin-top: 8px; + margin-bottom: 8px; +} + +.md-typeset details.announcement div.dates { + align-items: stretch; + display: grid; + grid-template-columns: auto 1fr; +} + +.md-typeset details.announcement div.effective-dates { + float: left; + text-align: left; +} + +.md-typeset details.announcement div.posted-date { + float: right; + text-align: right; +} + + /* construction admonition */ .md-typeset .admonition.construction, .md-typeset details.construction { @@ -107,53 +218,229 @@ html .md-footer-meta.md-typeset a.supportemail { .md-typeset .construction>.admonition-title::before, .md-typeset .construction>summary::before { - background-color: var(--announcement-admonition-bd-color); - -webkit-mask-image: var(--md-admonition-icon--warning); - mask-image: var(--md-admonition-icon--warning); + background-color: var(--construction-admonition-bd-color); + -webkit-mask-image: var(--md-admonition-icon--material-crane); + mask-image: var(--md-admonition-icon--material-crane); } -/* announcement admonition */ -.md-typeset .admonition.announcement, -.md-typeset details.announcement { - border-color: var(--announcement-admonition-bd-color); +/* important admonition */ +.md-typeset .admonition.important, +.md-typeset details.important { + border-color: var(--important-admonition-bd-color); } -.md-typeset .announcement>.admonition-title, -.md-typeset .announcement>summary { - background-color: var(--announcement-admonition-bg-color); - border-color: var(--announcement-admonition-bd-color); +.md-typeset .important>.admonition-title, +.md-typeset .important>summary { + background-color: var(--important-admonition-bg-color); + border-color: var(--important-admonition-bd-color); } -.md-typeset .announcement>.admonition-title::before, -.md-typeset .announcement>summary::before { - background-color: var(--announcement-admonition-bd-color); - -webkit-mask-image: var(--md-admonition-icon--warning); - mask-image: var(--md-admonition-icon--warning); +.md-typeset .important>.admonition-title::before, +.md-typeset .important>summary::before { + background-color: var(--important-admonition-bd-color); + -webkit-mask-image: var(--md-admonition-icon--material-decagram-alert); + mask-image: var(--md-admonition-icon--material-decagram-alert); } -/* lightgallery and image tweaks */ +/* security admonition */ +.md-typeset .admonition.security, +.md-typeset details.security { + border-color: var(--security-admonition-bd-color); +} -/* image width */ -.md-grid { - max-width: 100%; +.md-typeset .security>.admonition-title, +.md-typeset .security>summary { + background-color: var(--security-admonition-bg-color); + border-color: var(--security-admonition-bd-color); +} + +.md-typeset .security>.admonition-title::before, +.md-typeset .security>summary::before { + background-color: var(--security-admonition-bd-color); + -webkit-mask-image: var(--md-admonition-icon--material-shield-alert); + mask-image: var(--md-admonition-icon--material-shield-alert); } -/* adds a flexbox to the surrounding div */ -a.glightbox { +/* GLIGHTBOX ADJUSTMENTS */ +/* image centering in content */ +.md-content a.glightbox { display: flex; justify-content: center; } -/* adding the drop shadow,margin and keeping the images at 50 viewport width */ -a.glightbox img { +/* drop shadow */ +.md-content a.glightbox img { max-width: 50vw; box-shadow: 5px 5px 13px var(--lightbox-shadow-color); margin-bottom: 1rem; } -/* 100 viewport width on smaller screens */ +/* media-appropriate widths */ +.md-grid { + max-width: 100%; +} + @media only screen and (max-width: 600px) { a.glightbox img { max-width: 100%; } } + +/* TABBED CONTENT ADJUSTMENTS */ +/* Give tabs more of a button look */ +.tabbed-labels label { + border: 1px solid var(--md-default-fg-color--lighter); + border-bottom: 0px !important; + border-radius: 6px 6px 0 0; + box-sizing: border-box; + padding: 0.4em 1em; + margin-right: 0.3em; + cursor: pointer; + background: var(--md-default-bg-color); + transition: background 0.2s, color 0.2s, border-color 0.2s; +} + +.tabbed-labels label>a { + border-bottom: 0px !important; +} + +/* On hover */ +.tabbed-labels label:hover { + background: var(--md-accent-fg-color--transparent); + border-color: var(--md-accent-fg-color); + color: var(--md-accent-fg-color); +} + +/* When active */ +/* .tabbed-labels input:checked+label { + background: var(--md-accent-fg-color); + color: white; + border-color: var(--md-accent-fg-color); + font-weight: 600; +} */ + +/* Bottom border to mark end of tabbed content */ +/* .tabbed-content { + border-bottom: 2px solid var(--md-default-fg-color--lighter); + padding-bottom: 0.75rem; + margin-bottom: 1rem; +} */ +.tabbed-content { + border: 1px solid var(--md-default-fg-color--lighter); + border-top: 1px solid var(--md-default-fg-color--lighter) !important; + /* so it connects with the tabs */ + padding: 1rem; + /* margin-bottom: 1.5rem; */ + border-radius: 0 0 6px 6px; +} + +.md-typeset .tabbed-set>.tabbed-labels.tabbed-labels--linked { + box-sizing: border-box; + box-shadow: none; + border-bottom: 0px !important; + /* background-color: rgba(0, 0, 0, 0); */ + border-bottom: 1px solid var(--md-default-fg-color--lighter); +} + +/* GRID CARDS ADJUSTMENTS */ +/* full-card link styling */ +.md-typeset .grid.cards ul>li { + position: relative; + display: flex; + flex-direction: column; +} + +.md-typeset .grid.cards ul>li p:has(.overlay-link) { + margin-bottom: 0; + margin-top: 0; +} + +.grid.cards .overlay-link { + position: absolute; + top: 0; + left: 0; + bottom: 0; + right: 0; + width: 100%; + height: 100%; +} + +/* END full-card link styling */ + +/* separate title icon from title text for consistent spacing */ +.md-typeset .grid.cards ul>li p span.twemoji:after { + /* literal "em space" U+2003 character, do not change or delete */ + content: " "; +} + +/* tail link placement consistency at bottom of card */ +.md-typeset .grid.cards ul>li p:last-child:has(a) { + margin-top: auto; +} + +/* pleasing max width of single cards */ +.md-typeset .grid.cards ul>li:only-child { + width: min(100%, 450px); +} + +/* lists in grid cards */ +.md-typeset .grid.cards ul ul { + list-style-type: disc; +} + +.md-typeset .grid.cards ul ul>li { + display: list-item; +} + +.md-typeset .grid.cards ul ol { + list-style-type: decimal; +} + +.md-typeset .grid.cards ul ol>li { + display: list-item; +} + +.md-typeset .grid.cards ul ol ol { + list-style-type: lower-alpha; +} + +.md-typeset .grid.cards ul ol ol>li { + display: list-item; +} + +.md-typeset .grid.cards ul ol ol ol { + list-style-type: lower-roman; +} + +.md-typeset .grid.cards ul ol ol ol>li { + display: list-item; +} + +/* EMOJI ICON COLORS */ +.icon-color-uab-green { + color: var(--uab-color-uab-green); +} + +.icon-color-dragons-lair-green { + color: var(--uab-color-dragons-lair-green) +} + +.icon-color-openstack-red { + color: #ed1944 +} + +.icon-color-gitlab-orange { + color: #fc6d26 +} + +.icon-color-globus-blue { + color: #32619b +} + +.icon-color-jupyter-orange { + color: #f37626 +} + +.icon-color-rstudio-blue { + color: #75aadb +} diff --git a/docs/uab_cloud/index.md b/docs/uab_cloud/index.md index 0d4923150..d8969f395 100644 --- a/docs/uab_cloud/index.md +++ b/docs/uab_cloud/index.md @@ -49,3 +49,13 @@ Please use the following rules when naming entities: - Must: use only letters, numbers, dash `-` and underscore `_`. - Must: have the first character in the name be a letter. - Should: use short, descriptive, memorable names. + +## Frequently Asked Questions + +- **How Do I Access Cloud.rc?** + + - To access the Cloud.rc, you must be on the campus network. + - For off-campus access, use the [UAB Campus VPN](https://www.uab.edu/it/home/tech-solutions/network/vpn), which requires [Duo 2FA](https://www.uab.edu/it/home/security/2-factor). + - UAB employees and students can log in using their BlazerID + - External Collaborators can use their XIAS email. + - For login details, visit our [Cloud.rc](#first-steps) section. diff --git a/docs/uab_cloud/remote_access.md b/docs/uab_cloud/remote_access.md index d52dd4158..d13f6dc42 100644 --- a/docs/uab_cloud/remote_access.md +++ b/docs/uab_cloud/remote_access.md @@ -222,13 +222,13 @@ ssh @ -i Where `user` is the remote username, `remote_ip` is the IP address of the remote machine, and `` is the private key file used for access the remote machine. See [Generating Key Pairs](#generating-key-pairs) for general instructions on creating a key pair, or [Creating a Key Pair](tutorial/security.md#creating-a-key-pair) for cloud.rc specific instructions. -## Make Instances Publically Accessible From the Internet +## Make Instances Publicly Accessible From the Internet -It is possible to make [instances](./tutorial/instances.md) publically accessible from the external internet. [Floating IPs](./tutorial/networks.md#floating-ips) are pulled from a limited and fixed pool of public IP addresses assigned from the overall UAB IP pool. By default, these IP addresses are unable to communicate beyond the UAB Internet Border firewall, for security reasons. To make your instance publically accessible, a Firewall Security Exception must be filed. The result of the security exception is to create a firewall rule to allow traffic between the internet and an application on your instance. This section will go over how to make your instance publically accessible. +It is possible to make [instances](./tutorial/instances.md) publicly accessible from the external internet. [Floating IPs](./tutorial/networks.md#floating-ips) are pulled from a limited and fixed pool of public IP addresses assigned from the overall UAB IP pool. By default, these IP addresses are unable to communicate beyond the UAB Internet Border firewall, for security reasons. To make your instance publicly accessible, a Firewall Security Exception must be filed. The result of the security exception is to create a firewall rule to allow traffic between the internet and an application on your instance. This section will go over how to make your instance publicly accessible. ### Expectations -The expectation of making an instance publically accessible is to advance UAB's mission, so be sure you've configured and thoroughly tested your instance in the UAB Campus Network before proceeding. The following list is intended as a helpful reminder. +The expectation of making an instance publicly accessible is to advance UAB's mission, so be sure you've configured and thoroughly tested your instance in the UAB Campus Network before proceeding. The following list is intended as a helpful reminder. - Have an instance with some research application or server that advances UAB's mission. - The instance is configured with a floating IP address. diff --git a/docs/uab_cloud/tutorial/index.md b/docs/uab_cloud/tutorial/index.md index e4e4b1391..8ee7ca29b 100644 --- a/docs/uab_cloud/tutorial/index.md +++ b/docs/uab_cloud/tutorial/index.md @@ -32,4 +32,4 @@ Once you have completed the tutorial, you might read over some of the following - [Remote Access](../remote_access.md) - Different ways to access instances. - [Installing Software](../installing_software.md) - Good practices and examples of installing common software. - [Snapshots](../snapshots.md) - Creating reusable custom images based on VMs you've spent time configuring. -- [Make an instance accessible by the public Internet](../remote_access.md#make-instances-publically-accessible-from-the-internet). +- [Make an instance accessible by the public Internet](../remote_access.md#make-instances-publicly-accessible-from-the-internet). diff --git a/docs/workflow_solutions/getting_containers.md b/docs/workflow_solutions/getting_containers.md index 6ecc2f98a..a9653816d 100644 --- a/docs/workflow_solutions/getting_containers.md +++ b/docs/workflow_solutions/getting_containers.md @@ -299,9 +299,9 @@ python python_test.py More lessons on Docker can be found in this link: [Introduction to Docker](https://christinalk.github.io/docker-introduction/) and [Docker Documentation](https://docs.docker.com/reference/dockerfile/). -## How to Access and Use Community Containers in the GitLab Container Registry +## How to Access and Use Community Containers in the Code.rc Container Registry -In the UAB Research Computing [GitLab instance](../account_management/gitlab_account.md#uab-gitlab-registration), we provide prebuilt community containers. These containers are standardized environments that grant you access to a variety of software tools. In the sections below we share information for what you will find in the gitlab community container project, and how you can access them. +In [Code.rc](../account/code.rc/index.md), we provide prebuilt community containers. These containers are standardized environments that grant you access to a variety of software tools. In the sections below we share information for what you will find in the gitlab community container project, and how you can access them. ### Software We Support in Building Community Containers @@ -365,7 +365,7 @@ If you prefer to share your container with a particular team/group, then the UAB The following steps help you to create a container registry in UAB GitLab: -1. Create a UAB Gitlab account following the guidelines from the [UAB GitLab page](../account_management/gitlab_account.md). +1. Create a Code.rc account following the guidelines from the [Code.rc page](../account/code.rc/create.md). 1. Create a `new_project` on UAB GitLab and click `Package and Registries`, and then go to `Container Registry`. Initially, the container registry looks empty because there are no container images in the registry. ![!Containers registry.](./images/containers_registry.png) diff --git a/docs/workflow_solutions/git_collaboration.md b/docs/workflow_solutions/git_collaboration.md index cd40a4319..a2544f8f0 100644 --- a/docs/workflow_solutions/git_collaboration.md +++ b/docs/workflow_solutions/git_collaboration.md @@ -39,7 +39,7 @@ More in-depth instructions, including for SSH cloning, are provided at the [offi ### Cloning From GitLab -To do anything with our GitLab instance, you will first need to create an account. Please see our [GitLab Account Management page](../account_management/gitlab_account.md). +To do anything with Code.rc, you will first need to create an account. Please see our [Code.rc Account Creation page](../account/code.rc/create.md). To clone a repository, be sure you have the repository URL. Then, using `git` at a terminal, [clone](git.md#cloning) the repository using whatever settings are appropriate. Be sure to append `.git` to the end of the repository or the clone will note be successful. For example, if the URL is `https://code.rc.uab.edu/user/repository` then you will clone `https://code.rc.uab.edu/user/repository.git`. GitLab repository pages look like the example shown below. @@ -64,7 +64,7 @@ An important feature, used extensively for this documentation's GitHub repositor - Want to collaborate publicly and outside UAB? Consider using GitHub. - Want your project private or internal to UAB? Consider using our GitLab instance. -It is possible to collaborate publicly using GitLab, but there may be additional challenges. While external collaborators can see a public GitLab repository on our instance, they can't make any changes or create issues without a [XIAS Account](../account_management/xias/index.md). +It is possible to collaborate publicly using GitLab, but there may be additional challenges. While external collaborators can see a public GitLab repository on our instance, they can't make any changes or create issues without a [XIAS Account](../account/code.rc/index.md). It is possible to collaborate privately using GitHub with no additional hurdles, but if your project contains sensitive or protected information of any kinds, it should not be posted to GitHub, even in private repositories. Please consult with us via [Support](../help/support.md) before diff --git a/macros/__init__.py b/macros/__init__.py new file mode 100644 index 000000000..e2bb8bc45 --- /dev/null +++ b/macros/__init__.py @@ -0,0 +1,55 @@ +"""Grid Card macro definitions.""" + +from __future__ import annotations + +from pathlib import Path, PurePath +from typing import TYPE_CHECKING, Callable + +import yaml + +from macros.util import normalize_page_link + +from .card import CardNamespace +from .render import CardRenderer + +if TYPE_CHECKING: + from mkdocs.structure.pages import Page + from mkdocs_macros.plugin import MacrosPlugin + + +def define_env(env: MacrosPlugin) -> None: + """Define grid card macros for use in docs.""" + + def render_j2() -> Callable[[str], str]: + def fn(raw_md: str) -> str: + template = env.env.from_string(raw_md) + return template.render(env.variables) + + return fn + + def get_page() -> Callable[[], Page]: + def fn() -> Page: + return env.page + + return fn + + renderer = CardRenderer( + render_j2(), + get_page(), + ) + + cards_path = PurePath("res/grid_cards.yml") + with Path(cards_path).open("r", encoding="utf-8") as f: + content = yaml.safe_load(f) + cards = CardNamespace.from_yaml("cards", content) + + env.variables["cards"] = cards + env.variables["renderer"] = renderer + + @env.filter + def normalize_link(link_target: str) -> str: + return normalize_page_link( + page_url=PurePath(env.page.url), + link_target=link_target, + page_is_index=env.page.is_index, + ) diff --git a/macros/base.py b/macros/base.py new file mode 100644 index 000000000..a06007705 --- /dev/null +++ b/macros/base.py @@ -0,0 +1,40 @@ +"""Base definitions for Grid Card objects.""" + +from __future__ import annotations + +import abc +from dataclasses import dataclass, field +from typing import TYPE_CHECKING, Self + +if TYPE_CHECKING: + from macros.card import CardNamespace + + +@dataclass +class CardElement: + """Base CardElement.""" + + name: str + parent: CardNamespace | None = field(default=None, init=False) + + def __post_init__(self) -> None: + """Validate card element name.""" + if not self.name.isidentifier(): + msg = "CardElement name must be a valid identifier." + raise ValueError(msg) + + def get_path(self) -> str: + """Get path of this namespace down to root.""" + parts: list[str] = [] + element = self + + while element.parent: + parts.append(element.name) + element = element.parent + + return ".".join(reversed(parts)) + + @classmethod + @abc.abstractmethod + def from_yaml(cls, name: str, content: dict) -> Self: + """Build from YAML.""" diff --git a/macros/card.py b/macros/card.py new file mode 100644 index 000000000..1906abdef --- /dev/null +++ b/macros/card.py @@ -0,0 +1,170 @@ +"""Grid Card definitions. + +Derives from CardElement for shared elements. + +Leaves of a tree structure. +""" + +from __future__ import annotations + +import enum +from dataclasses import dataclass, field +from types import SimpleNamespace +from typing import Literal, Self, overload + +from macros.base import CardElement + + +class EmojiSizesCss(enum.Enum): + """CSS Emoji Sizes.""" + + standard = "" + large = ".lg" + xlarge = ".xlg" + xxlarge = ".xxlg" + xxxlarge = ".xxxlg" + + @classmethod + def default(cls) -> EmojiSizesCss: + """Return default.""" + return cls.large + + +class EmojiVerticalAlignmentCss(enum.Enum): + """CSS Emoji Vertical Alignments.""" + + standard = "" + middle = ".middle" + + @classmethod + def default(cls) -> EmojiVerticalAlignmentCss: + """Return default.""" + return cls.middle + + +@dataclass +class Card(CardElement): + """Representation of a grid card.""" + + title_text: str + title_url: str | None = None + + icon_name: str | None = None + icon_color: str | None = None + icon_size: EmojiSizesCss | None = None + icon_vertical_alignment: EmojiVerticalAlignmentCss | None = None + content: str | None = None + + link_url: str | None = None + link_text: str | None = None + link_icon_name: str | None = None + + def __post_init__(self) -> None: + """Validate title text.""" + super().__post_init__() + if not self.title_text: + msg = "Card must have non-empty title." + raise ValueError(msg) + + @classmethod + def from_yaml(cls, name: str, content: dict) -> Self: + """Build card from YAML representation.""" + return cls( + name=name, + title_text=content["title_text"], + title_url=content.get("title_url"), + icon_name=content.get("icon_name"), + icon_color=content.get("icon_color"), + icon_size=content.get("icon_size"), + icon_vertical_alignment=content.get("icon_vertical_alignment"), + content=content.get("content"), + link_url=content.get("link_url"), + link_text=content.get("link_text"), + link_icon_name=content.get("link_icon_name"), + ) + + +@dataclass +class CardNamespace(CardElement, SimpleNamespace): + """Namespace of grid card collection.""" + + def __setattr__(self, name: str, value: CardNamespace | Card) -> None: + """Override setattr() and dot operator.""" + if name.startswith("_") or name in ("name", "parent"): + object.__setattr__(self, name, value) + return + if isinstance(value, (Card, CardNamespace)): + if hasattr(self, name): + path = self.get_path() + path = f"{path}.{name}" if path else name + msg = f"duplicate namespace or card found: {path}" + raise KeyError(msg) + value.parent = self + self._children.append(value) + object.__setattr__(self, name, value) + return + msg = "CardNamespace may only hold CardNamespace or Card." + raise TypeError(msg) + + @overload + def get_children( + self, + *, + recursive: bool = ..., + cards_only: Literal[False], + ) -> list[Card | CardNamespace]: ... + + @overload + def get_children( + self, + *, + recursive: bool = ..., + cards_only: Literal[True] = True, + ) -> list[Card]: ... + + def get_children( + self, + *, + recursive: bool = False, + cards_only: bool = True, + ) -> list[Card | CardNamespace] | list[Card]: + """Get all cards that are children of this card. + + If recursive is True, children of children, etc., are also returned, + depth first. + """ + children: list[Card | CardNamespace] = [] + for child in self._children: + if not cards_only or isinstance(child, Card): + children.append(child) + if isinstance(child, CardNamespace) and recursive: + children.extend( + child.get_children(recursive=recursive, cards_only=cards_only), + ) + return children + + def to_dict( + self, + *, + cards_only: bool = True, + ) -> dict[str, Card | CardNamespace] | dict[str, Card]: + """Children as dict of (path, Card). + + If cards_only is False, also returns CardNamespaces. + """ + return { + c.get_path(): c + for c in self.get_children(recursive=True, cards_only=cards_only) + } + + @classmethod + def from_yaml(cls, name: str, content: dict) -> Self: + """Build from YAML.""" + namespace = cls(name) + for child_name, child_content in content.items(): + child_type = Card if "title_text" in child_content else cls + child = child_type.from_yaml(child_name, child_content) + setattr(namespace, child_name, child) + return namespace + + _children: list[CardNamespace | Card] = field(default_factory=list) diff --git a/macros/render.py b/macros/render.py new file mode 100644 index 000000000..ba2126d70 --- /dev/null +++ b/macros/render.py @@ -0,0 +1,188 @@ +"""Model rendering.""" + +from __future__ import annotations + +import textwrap +from pathlib import PurePath +from typing import TYPE_CHECKING, Callable + +from macros.card import Card, CardNamespace, EmojiSizesCss, EmojiVerticalAlignmentCss +from macros.util import normalize_page_link + +if TYPE_CHECKING: + from mkdocs.structure.pages import Page + + +class CardRenderer: + """Handles rendering of cards.""" + + def __init__( + self, + render_j2: Callable[[str], str], + get_page: Callable[[], Page], + ) -> None: + """Initialize new object.""" + self._j2_renderer: Callable[[str], str] = render_j2 + self._get_page: Callable[[], Page] = get_page + + def render_cards(self, *cards: Card) -> str: + """Render input to markdown string. + + Intended for use with mkdocs-material grid cards. + """ + parts = [self._div_open] + extractors = [ + _CardExtractor(self._j2_renderer, self._get_page(), card) for card in cards + ] + card_parts = [ex.extract() for ex in extractors] + card_parts = [part for cards in card_parts for part in cards] + parts.extend(card_parts) + parts.append(self._div_close) + + template_raw = "\n\n" + "\n\n".join(parts) + "\n\n" + return self._j2_renderer(template_raw) + + def render_namespace( + self, + namespace: CardNamespace, + *, + recursive: bool = False, + ) -> str: + """Render input namespace to markdown string. + + Intended for use with mkdocs-material grid cards. + """ + cards = namespace.get_children(recursive=recursive, cards_only=True) + return self.render_cards(*cards) + + _div_open = r'
' + _div_close = r"
" + + +class _CardExtractor: + def __init__(self, render_j2: Callable[[str], str], page: Page, card: Card) -> None: + self._j2_renderer: Callable[[str], str] = render_j2 + self._page: Page = page + self._card: Card = card + self._indent: int = 4 + + def extract(self) -> list[str]: + indented_block = [] + content = self._content_part() + if content: + indented_block.append(content) + link = self._link_part() + if link: + indented_block.append(link) + if indented_block: + indented_block.insert(0, self._hr) + + parts = [self._title_part()] + parts.extend([self._clean_and_indent(part) for part in indented_block]) + return parts + + #### DEFAULTS + _DEFAULT_ICON_COLOR = ".icon-color-uab-green" + _DEFAULT_ICON_SIZE = EmojiSizesCss.large + _DEFAULT_ICON_VERTICAL_ALIGNMENT = EmojiVerticalAlignmentCss.middle + _DEFAULT_LINK_TEXT = "Read more" + _DEFAULT_LINK_ICON_NAME = ":octicons-arrow-right-24:" + + #### DEFINITIONS + _ul = "-" + _hr = "---" + + #### TITLE PART + def _title_part(self) -> str: + parts = [self._ul] + icon = self._icon() + if icon: + parts.append(icon) + parts.append(self._title()) + return " ".join(parts) + + ## TITLE + def _title(self) -> str: + text = self._title_text() + url = self._title_url() + return self._to_md_internal_link(text, url) if url else text + + def _title_text(self) -> str: + return f"**{self._card.title_text}**" + + def _title_url(self) -> str | None: + url = self._card.title_url + return self._prepare_url(url) if url else None + + ## ICON + def _icon(self) -> str | None: + name = self._icon_name() + css = self._icon_css() + if name and css: + return name + css + if name: + return name + return None + + def _icon_name(self) -> str | None: + return self._card.icon_name + + def _icon_css(self) -> str | None: + css_classes = [ + self._icon_size(), + self._icon_vertical_alignment(), + self._icon_color(), + ] + return "{ " + " ".join(css_classes) + " }" if css_classes else None + + def _icon_size(self) -> str: + size = self._card.icon_size + return size.value if size else EmojiSizesCss.default().value + + def _icon_vertical_alignment(self) -> str: + va = self._card.icon_vertical_alignment + return va.value if va else EmojiVerticalAlignmentCss.default().value + + def _icon_color(self) -> str: + color = self._card.icon_color + return color if color else self._DEFAULT_ICON_COLOR + + #### CONTENT PART + def _content_part(self) -> str | None: + return self._card.content + + #### LINK PART + def _link_part(self) -> str | None: + text = f"{self._link_text()} {self._link_icon()}" + url = self._link_url() + return self._to_md_internal_link(text, url) if url else None + + def _link_text(self) -> str: + text = self._card.link_text + return text if text else self._DEFAULT_LINK_TEXT + + def _link_icon(self) -> str: + name = self._card.link_icon_name + return name if name else self._DEFAULT_LINK_ICON_NAME + + def _link_url(self) -> str | None: + url = self._card.link_url + return self._prepare_url(url) if url else None + + #### HELPERS + def _clean_and_indent(self, s: str) -> str: + out = s + out = textwrap.dedent(out) + out = out.strip() + return textwrap.indent(out, " " * self._indent) + + def _prepare_url(self, link_target: str) -> str: + link_target = self._j2_renderer(link_target) + return normalize_page_link( + page_url=PurePath(self._page.url), + link_target=link_target, + page_is_index=self._page.is_index, + ) + + def _to_md_internal_link(self, text: str, url: str) -> str: + return f"[{text}]({url})" diff --git a/macros/util.py b/macros/util.py new file mode 100644 index 000000000..5dd8ed466 --- /dev/null +++ b/macros/util.py @@ -0,0 +1,89 @@ +"""Utilities for macros module.""" + +from __future__ import annotations + +import os +import re +from pathlib import PurePath + + +def normalize_page_link( + page_url: PurePath, + link_target: str, + *, + page_is_index: bool, +) -> str: + """Return normalized link in page. + + - [text](name@domain.com) -> name@domain.com + - [text](https://domain.com) -> https://domain.com + - [text](path/to/file.md) -> ../rel/to/page/file.md + """ + # external + if _is_email(link_target): + return f"mailto:{link_target}" + + if _is_uri(link_target): + return link_target + + # internal + page_url = page_url if page_is_index else page_url.parent + out = _to_rel_url(page_url, PurePath(link_target)) + + return out.as_posix() + + +def _to_rel_url( + source_sub_path: PurePath, + target_sub_path: PurePath, +) -> PurePath: + """Return relative url between source_sub_path and target_sub_path.""" + root = PurePath() + target_abs_url = root / target_sub_path + source_abs_url = root / source_sub_path + return PurePath(os.path.relpath(target_abs_url, source_abs_url)) + + +_J2_DELIMITERS = ( + ("{{", "}}"), + ("{%", "%}"), + ("{#", "#}"), +) + + +def _is_template(link_target: str) -> bool: + """Return true if Jinja template. + + - {{ ... }} + - {% ... %} + - {# ... #} + """ + return any( + link_target.startswith(start) and link_target.endswith(end) + for start, end in _J2_DELIMITERS + ) + + +def _is_email(link_target: str) -> bool: + return "@" in link_target + + +def _is_uri(link_target: str) -> bool: + return bool(re.fullmatch(r"^.*://.*$", link_target)) + + +if __name__ == "__main__": + cases = ( + ("a@b.c", "a@b.c"), + ("s://a.b/", "s://a.b/"), + ("a.md", "a.md"), + ("index.md", "index.md"), + ("a/b.md", "a/b.md"), + ("a/index.md", "a/index.md"), + ("../index.md", "../index.md"), + ("../a.md", "../a.md"), + ) + expected = ( + "name@domain.com", + "", + ) diff --git a/mkdocs.yml b/mkdocs.yml index 0f83ff2eb..6072e8352 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,6 +12,7 @@ theme: - navigation.instant - content.code.copy - content.action.edit + - content.tabs.link favicon: images/favicon.png logo: images/logo.png @@ -32,10 +33,19 @@ markdown_extensions: - pymdownx.arithmatex: generic: true - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:material.extensions.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji - pymdownx.highlight: anchor_linenums: true - pymdownx.keys - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + combine_header_slug: true + slugify: !!python/object/apply:pymdownx.slugs.slugify + kwds: + case: lower - tables - toc: permalink: true @@ -63,16 +73,34 @@ plugins: # order matters! type: date strict: false - glightbox + - macros: + include_yaml: + - res/announcements.yml + - res/docs_template_context.yml + j2_extensions: + - jinja2_workarounds.MultiLineInclude + module_name: macros + on_undefined: strict + render_by_default: true + verbose: true - table-reader: data_path: docs - title-casing - redirects: redirect_maps: - account_management/gitlab_researcher.md: account_management/gitlab_account.md - account_management/uab_researcher.md: account_management/cheaha_account.md - account_management/xias_guest.md: account_management/xias/guest_instructions.md - account_management/xias_sites.md: account_management/xias/pi_site_management.md - account_management/xias_users.md: account_management/xias/pi_guest_management.md + account_management/cheaha_account.md: account/rcs/index.md + account_management/gitlab_account.md: account/code.rc/index.md + account_management/gitlab_researcher.md: account/code.rc/index.md + account_management/index.md: account/index.md + account_management/leaving_uab.md: account/leaving/index.md + account_management/uab_researcher.md: account/rcs/index.md + account_management/xias/guest_instructions.md: account/xias/3_guest_create_xias_account.md + account_management/xias/index.md: account/xias/index.md + account_management/xias/pi_guest_management.md: account/xias/2_sponsor_manage_users.md + account_management/xias/pi_site_management.md: account/xias/1_sponsor_manage_sites.md + account_management/xias_guest.md: account/xias/3_guest_create_xias_account.md + account_management/xias_sites.md: account/xias/1_sponsor_manage_sites.md + account_management/xias_users.md: account/xias/2_sponsor_manage_users.md cheaha/conda.md: cheaha/software/software.md#anaconda-on-cheaha cheaha/lmod.md: cheaha/software/modules.md cheaha/open_ondemand/ood_files.md: cheaha/open_ondemand/ood_layout.md @@ -82,9 +110,9 @@ plugins: # order matters! cheaha/open_ondemand/ood_jupyter.md: cheaha/open_ondemand/ood_jupyter_notebook.md cheaha/slurm/sbatch_usage.md: cheaha/slurm/submitting_jobs.md contributor_guide.md: contributing/contributor_guide.md - data_management/cheaha_gpfs_storage.md: data_management/cheaha_storage_gpfs/index.md data_management/LTS/lts.md: data_management/lts/index.md data_management/LTS/sharing.md: data_management/lts/iam_and_policies.md + data_management/cheaha_gpfs_storage.md: data_management/cheaha_storage_gpfs/index.md data_management/lts/lts.md: data_management/lts/index.md data_management/lts/policies.md: data_management/lts/iam_and_policies.md data_management/lts/sharing.md: data_management/lts/iam_and_policies.md @@ -105,24 +133,39 @@ plugins: # order matters! exclude_docs: | /**/res/*.md + /**/_macro/ + /**/_template/ not_in_nav: | /**/res/*.md + /**/_macro/ + /**/_template/ nav: - Home: index.md - News: - news/index.md - Account Management: - - account_management/index.md - - Cheaha Account: account_management/cheaha_account.md - - External Collaborator Accounts (XIAS): - - account_management/xias/index.md - - "For PIs - (1) Managing Projects & Sites": account_management/xias/pi_site_management.md - - "For PIs - (2) Managing Guests": account_management/xias/pi_guest_management.md - - "For Guests - Account Creation": account_management/xias/guest_instructions.md - - GitLab Account: account_management/gitlab_account.md - - Leaving UAB: account_management/leaving_uab.md + - account/index.md + - Research Computing System (RCS): + - account/rcs/index.md + - Create: account/rcs/create.md + - Status: account/rcs/status.md + - Code.rc (GitLab): + - account/code.rc/index.md + - Create: account/code.rc/create.md + - Manage: account/code.rc/manage.md + - External Collaborators: + - account/xias/index.md + - 1. Sponsor — Manage Sites: account/xias/1_sponsor_manage_sites.md + - 2. Sponsor — Manage Users: account/xias/2_sponsor_manage_users.md + - 3. Guests — Create XIAS Account: account/xias/3_guest_create_xias_account.md + - 4. Guests — Create RCS Account: account/rcs/create.md + - Your Responsibilities: account/responsibilities.md + - Leaving UAB: + - account/leaving/index.md + - Continuing Collaboration: account/leaving/collaboration.md + - Final Steps: account/leaving/final_steps.md - Data Management: - data_management/index.md - Cheaha Storage (GPFS): @@ -206,6 +249,8 @@ nav: - kubernetes/index.md - Startup: kubernetes/startup.md - Hardware: kubernetes/hardware.md + - Code.rc (GitLab) Guide: + - code.rc/index.md - National Research Computing Cyberinfrastructure: - national_ci/index.md - The Open Science Grid: national_ci/osg.md @@ -245,5 +290,7 @@ validation: unrecognized_links: warn watch: + - macros + - res - scripts - theme diff --git a/res/.announcements_schema.yml b/res/.announcements_schema.yml new file mode 100644 index 000000000..8331f12e5 --- /dev/null +++ b/res/.announcements_schema.yml @@ -0,0 +1,82 @@ +type: object +required: + - announcements + - no_announcements + - _example_announcement_do_not_use +additionalProperties: false +properties: + announcements: + ref: "#/definitions/announcements" + no_announcements: + ref: "#/definitions/announcements" + _example_announcement_do_not_use: + ref: "#/definitions/example_announcement" + +definitions: + announcements: + type: array + title: Announcements + description: | + A list of Announcement objects. + items: + ref: "#/definitions/announcement" + + no_announcements: + type: string + title: No Announcements + description: | + A string displayed as the title of an empty "info" admonition. + Only displayed when Announcements is empty. + + example_announcement: + ref: "#/definitions/announcement" + + announcement: + type: object + title: Announcement + description: | + An announcement to be displayed on the front page. + required: + - title + - content + - posted_date + optional: + - end_date + - start_date + additionalProperties: false + properties: + title: + ref: "#/definitions/title" + content: + ref: "#/definitions/content" + posted_date: + ref: "#/definitions/date" + end_date: + ref: "#/definitions/date" + start_date: + ref: "#/definitions/date" + + title: + type: string + title: Announcement Title + description: | + A brief, descriptive, single-line title for the announcement. + Will appear as "Announcement: ...". + minLength: 1 + + content: + type: string + title: Announcement Content + description: | + Markdown content to describe the card. + Inline Markdown formatting may be used. + Links to other pages are allowed. + Please keep it relatively brief. + minLength: 1 + + date: + type: string + title: Date + description: | + An ISO 8601 compliant date (YYYY-MM-DD). + pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" diff --git a/res/.grid_cards_schema.yml b/res/.grid_cards_schema.yml new file mode 100644 index 000000000..186d18449 --- /dev/null +++ b/res/.grid_cards_schema.yml @@ -0,0 +1,154 @@ +$ref: "#/definitions/namespace" + +definitions: + namespace: + type: object + title: Namespace + description: | + A namespace for organizing grid cards. + minProperties: 1 + propertyNames: + pattern: "^(?!^title_text|name|parent|_children$).*$" + patternProperties: + "^(?!^title_text|name|parent|_children$).*$": + oneOf: + - $ref: "#/definitions/namespace" + - $ref: "#/definitions/content_card" + - $ref: "#/definitions/title_card" + + content_card: + type: object + title: Content Card + description: | + The definition for a card with descriptive content. + Content and a link url are both required. + All fields are allowed except the title URL. + required: + - title_text + - content + - link_url + additionalProperties: false + properties: + title_text: + ref: "#/definitions/title_text" + icon_name: + ref: "#/definitions/icon_name" + icon_color: + ref: "#/definitions/icon_color" + icon_size: + ref: "#/definitions/icon_size" + icon_vertical_alignment: + ref: "#/definitions/icon_vertical_alignment" + content: + ref: "#/definitions/content" + link_text: + ref: "#/definitions/link_text" + link_url: + ref: "#/definitions/link_url" + link_icon_name: + ref: "#/definitions/icon_name" + + title_card: + type: object + title: Title-only Card + description: | + The definition for a card with only a title line. + A URL must be supplied so the title links to a page or section. + Icon information may be supplied. + No other information is allowed. + required: + - title_text + - title_url + additionalProperties: false + properties: + title_text: + ref: "#/definitions/title_text" + title_url: + ref: "#/definitions/link_url" + icon_name: + ref: "#/definitions/icon_name" + icon_color: + ref: "#/definitions/icon_color" + icon_size: + ref: "#/definitions/icon_size" + icon_vertical_alignment: + ref: "#/definitions/icon_vertical_alignment" + + title_text: + type: string + title: Card Title Text + description: | + A brief, descriptive, single-line title for the card. + Inline Markdown formatting may be used, such as links. + minLength: 1 + + content: + type: string + title: Card Markdown Content + description: | + Markdown content to describe the card. + Inline and block Markdown formatting may be used. + Links to other pages are encouraged. + Please keep it relatively brief. + Nested blocks are not recommended. + minLength: 1 + + link_text: + type: string + title: Absolute Internal Link Text + description: | + Optional text to use as link text for "link_url". + Defaults to "Read more". + minLength: 1 + + link_url: + type: string + title: Absolute Internal Link URL + description: | + Absolute url from within "docs_dir" to referenced page or section. + minLength: 1 + + icon_name: + type: string + title: Mkdocs Material Theme Icon Name + description: | + Icon name, formatted like ":icon-name:". + Icons come from https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/?h=emoji. + An eye-catching, relevant icon is recommended. + minLength: 1 + pattern: "^:([a-z0-9]+)(-[a-z0-9]+)*:$" + + icon_color: + type: string + title: Icon Color CSS Class + description: | + Icon color. + The icon color must be formatted like ".icon-name-...". + Colors must be defined as CSS classes in "docs/stylesheets/extra.css" + minLength: 13 + pattern: "^\\.icon-color-[a-z0-9]+[a-z0-9-]*$" + + icon_size: + type: string + title: Icon Size + description: | + Icon size. + A CSS class indicating desired icon size. + These come from the Mkdocs Material theme. + enum: + - "" + - ".lg" + - ".xlg" + - ".xxlg" + - ".xxxlg" + + icon_vertical_alignment: + type: string + title: Icon Vertical Alignment + description: | + Icon vertical alignment. + A CSS class indicating desired icon vertical alignment. + These come from the Mkdocs Material theme. + enum: + - "" + - ".middle" diff --git a/res/announcements.yml b/res/announcements.yml new file mode 100644 index 000000000..a3a4543f0 --- /dev/null +++ b/res/announcements.yml @@ -0,0 +1,23 @@ +announcements: + # Add announcements like the example. You can have multiple announcements. + # Copy-paste the example announcement under this key for each announcement. + - title: Ongoing Cheaha (GPFS) Data Migration + content: | + Research Computing will be performing a data migration for Cheaha. + Please see our [migration overview](./news/posts/2025-10-07-migration-overview.md) + for more information on what to expect. + posted_date: 2025-10-07 + start_date: 2025-10-11 + end_date: 2025-11-30 + +no_announcements: '!!! info "Look for future announcements here."' + +_example_announcement_do_not_use: + - title: Title + content: | + Content + + More Content + posted_date: 2025-10-17 + start_date: 2025-11-10 + end_date: 2025-11-25 diff --git a/res/docs_template_context.yml b/res/docs_template_context.yml new file mode 100644 index 000000000..e71d3bfd3 --- /dev/null +++ b/res/docs_template_context.yml @@ -0,0 +1,25 @@ +account: + leaving: + grace_period_time: thirty (30) day +storage: + no_cost: + individual: + gpfs: 5 TB on Cheaha (GPFS) + lts: 5 TB on Long-Term Storage (LTS) + shared: + gpfs: 25 TB on Cheaha (GPFS) + lts: 75 TB on Long-Term Storage (LTS) +support: + email: support@listserv.uab.edu + office_hours: + timezone: Central Time + url: https://uab.zoom.us/j/81783104592?pwd=L21OOWNlY2doWXova3MzOGFRcE4zQT09 + events: + - day: Monday + starttime: 10:00 AM + endtime: 12:00 PM + - day: Thursday + starttime: 10:00 AM + endtime: 12:00 PM + servicenow_url: https://uabprod.service-now.com/service_portal + statuscast_url: https://uabstatus.statuscast.com/#!/incidentlist?componentId=34990 diff --git a/res/grid_cards.yml b/res/grid_cards.yml new file mode 100644 index 000000000..aed9f5f60 --- /dev/null +++ b/res/grid_cards.yml @@ -0,0 +1,233 @@ +account: + xias_create: + title_text: Create Account (External) + icon_name: ":material-account-network:" + content: | + Are you an external collaborator? + Do you need to sponsor an external collaborator? + Create an external collaborator (XIAS) account today! + link_url: "account/xias/index.md" + leaving: + title_text: Leaving UAB? + icon_name: ":material-account-off:" + content: | + Planning to leave UAB? + Want to learn happens to your data and system access? + link_url: "account/leaving/index.md" + responsibilities: + title_text: Responsibilities and Policies + icon_name: ":material-clipboard-check-multiple:" + content: | + Want to learn who is responsible for what, and what to expect on our systems? + Become familiar with RCS responsibilities, expectations, and policies. + link_url: "account/responsibilities.md" + + code_rc_create: + title_text: Create Code.rc (GitLab) Account + icon_name: ":simple-gitlab:" + icon_color: .icon-color-gitlab-orange + content: | + Need a place to securely store code? + Store git repositories in our on-premises GitLab server. + Create a Code.rc account today! + link_url: "account/code.rc/create.md" + rcs: + create: + title_text: Create Account (RCS / Cheaha) + icon_name: ":material-account-plus:" + content: | + Affiliated with UAB? + Need access to Cheaha, Cloud.rc, Code.rc, or other RCS services? + Create an RCS account today in minutes! + link_url: "account/rcs/create.md" + status: + title_text: Check Account Status + icon_name: ":material-account-cog:" + content: | + Want to check your RCS account status? + Learn about account statuses and what they mean. + link_url: "account/rcs/status.md" + xias: + sponsor_site: + title_text: 1. Sponsor — Create Site + icon_name: ":material-sitemap:" + content: | + First, the Sponsor will need to configure a Site. + The Site allows configuring Guests. + link_url: "account/xias/1_sponsor_manage_sites.md" + sponsor_user: + title_text: 2. Sponsor — Create User + icon_name: ":material-account-multiple-plus:" + content: | + Second, the Sponsor will need to configure a User for the Guest. + User configuration allows Guest account creation. + link_url: "account/xias/2_sponsor_manage_users.md" + guest_instructions: + title_text: 3. Guest — Create XIAS Account + icon_name: ":material-clipboard-account:" + content: | + Third, the Guest should follow these instructions to create their XIAS account. + link_url: "account/xias/3_guest_create_xias_account.md" + guest_create_rcs: + title_text: 4. Guest — Create RCS Account + icon_name: ":material-account-plus:" + content: | + Lastly, the Guest may now create an RCS account. + link_url: "account/rcs/create.md" + manage_site: + title_text: Sponsor — Manage Site + icon_name: ":material-cog-sync:" + content: | + Need to update Site URIs or end date, or add new Users? + link_url: "account/xias/1_sponsor_manage_sites.md#how-do-i-manage-a-xias-site" + manage_user: + title_text: Sponsor — Manage User + icon_name: ":material-account-cog:" + content: | + Need to update User end dates, or add to a new Site? + link_url: "account/xias/2_sponsor_manage_users.md#how-do-i-manage-a-xias-user" + +news: + title_text: UAB RCS News + icon_name: ":fontawesome-solid-newspaper:" + content: | + See what's new with Research Computing System services! + link_url: "news/index.md" + +education: + training: + title_text: Training Resources + icon_name: ":material-notebook-edit:" + content: | + See our collection of internet training resources! + link_url: "education/training_resources.md" + dsjc: + title_text: Data Science Journal Club Course + icon_name: ":octicons-mortar-board-24:" + content: | + We offer a 1 credit hour course: Data Science Journal Club. + link_url: "education/courses.md#data-science-journal-club-course" + +platforms: + cheaha: + ood: + overview: + title_text: Open OnDemand Web Interface + icon_name: ":octicons-browser-24:" + content: | + Check out our interactive science apps, right in your browser! + Jupyter, RStudio, MATLAB, a virtual desktop, and more! + link_url: "cheaha/open_ondemand/index.md" + slurm: + overview: + title_text: Slurm Batch Job Scheduler + icon_name: ":material-script-text-play:" + content: | + Scale up your work! + Learn how to schedule batch jobs with Slurm. + link_url: "cheaha/slurm/introduction.md" + cloud_rc: + overview: + title_text: Cloud.rc (OpenStack) + icon_name: ":material-cloud-braces:" + content: | + Create virtual infrastructure to serve pages, build containers, and more! + link_url: "uab_cloud/index.md" + web_server: + title_text: Web Servers on Cloud.rc + icon_name: ":material-web:" + content: | + Learn how to make your Cloud.rc application public on the internet! + link_url: "uab_cloud/remote_access.md#make-instances-publicly-accessible-from-the-internet" + +data: + individual_storage: + title_text: Individual Storage Allocations + icon_name: ":material-server-network:" + content: | + Did you know researchers can get no-cost individual storage on RCS? + + - {{ storage.no_cost.individual.gpfs }} + - {{ storage.no_cost.individual.lts }} + link_url: "data_management/index.md" + shared_storage: + title_text: Shared Storage Allocations + icon_name: ":material-server-network:" + content: | + Did you know research labs and Cores can get no-cost shared storage on RCS? + + - {{ storage.no_cost.shared.gpfs }} + - {{ storage.no_cost.shared.lts }} + link_url: "data_management/index.md" + transfer_options: + title_text: Data Transfer Options + icon_name: ":material-transfer:" + content: | + RCS has multiple options for data transfers, within UAB and with other institutions. + Globus, rclone, and more! + link_url: "data_management/transfer/index.md" + +support: + email: + title_text: Have a Request? + icon_name: ":material-email-edit:" + content: | + Have a request? Facing an issue? Want to scale up? + link_text: Send us an email! + link_icon_name: ":material-email-fast:" + link_url: "{{ support.email }}" + office_hours: + title_text: Want Virtual Face-to-Face Support? + icon_name: ":simple-zoom:" + content: | + Visit our Zoom office hours! + + {% for event in support.office_hours.events %} + - {{ event.day }}: {{ event.starttime }} to {{ event.endtime }} {{support.office_hours.timezone }} | [Zoom]({{ support.office_hours.url }}) + {% endfor %} + link_text: null + link_icon_name: null + link_url: null + servicenow: + title_text: Check Your Support Requests + icon_name: ":material-progress-question:" + content: | + Create, review, and respond to service requests with the UAB ServiceNow Portal. + link_url: "{{ support.servicenow_url }}" + statuscast: + title_text: RCS Status Monitor + icon_name: ":material-bell:" + content: | + Check our StatusCast page for the latest on upcoming maintenance windows. + + Subscribe by clicking the bell at the StatusCast page. + link_text: "Go To Statuscast" + link_icon_name: null + link_url: "{{ support.statuscast_url }}" + page: + title_text: Need Support Details? + icon_name: ":material-help-network:" + content: | + Want to learn more about how to get Research Computing support? + link_url: "help/support.md" +# personas: +# administrative_staff: +# title_text: Administrative Staff +# icon_name: ":material-office-building:" +# content: | +# link_url: +# core_director: +# title_text: Core Director +# icon_name: ":material-desk:" +# external_collaborator: +# title_text: External Collaborator +# icon_name: ":material-clipboard-account:" +# research_faculty_lab_pi: +# title_text: Research Faculty Lab PI +# icon_name: ":material-account-group:" +# research_staff: +# title_text: Research Staff +# icon_name: ":material-test-tube:" +# student: +# title_text: Student +# icon_name: ":material-book-education:"