Subject: [LON-CAPA-dev] Draft of Release Notes for 2.12.0

From: "Raeburn, Stuart" <[email-masked]>
Date: Wed, 28 Jun 2023 16:50:02 +0000

New Version 2.12.0 to be released.

Update of 2.11.4 (and older) installations to 2.12.0 is highly recommended.
Changes from 2.11.4:

General Interface
- MathJax replaces TtH as the default math renderer for domains in which a
  default renderer has yet to be set.
- Each user may set a preferred time zone to use when displaying dates/times 
  if the user's domain config is set to allow it. (A course-specific time zone
  set by a Course Coordinator can override a user-specified one).
- The "Main menu" item/link (previously the left-most item in the second menu
  row) has been moved to the right side of top menu row, and renamed "Home".
- The Functions bar on the Courses/Roles screen will contain a "Show Pending"
  icon/link if role assignment(s) await approval by the role recipient.

Student Interface
- When the time-limit (interval) parameter is in effect for an item in a course,
  (e.g., for a timed quiz/exam) a button next to the countdown timer will allow 
  a student to end a timed quiz/exam early (when enabled in the interval parameter).
- The option to post anonymously to a discussion board in a course will be absent 
  when a Course Coordinator has disabled that for the current user's role or 
  specifically for the current user.
- A Chat link is included in the inline menu in a course unless "No Chat room use" 
  is in effect for the current student.

Course Management
- Shortcut URLs for direct access to a specific resource/folder in a course, without  
  the need for role selection, can be created via Course Editor > Content Utilities.
- Course Coordinators can define which standard menu items will be displayed to 
  students.  Different menu collection(s) can be set to apply when a session 
  in LON-CAPA is initiated via "deep linked" launch from another system.
- Link protection items for use with LTI-mediated "deep linked" access to resource(s)
  and/or folders in a course can be defined by a Course Coordinator, if the domain
  config permits it.
- A new "deeplink" parameter can require student access to resources and/or folders 
  in a course only by following a link from another web site/platform.
  The full set of options which can apply to the resource (or folder) for students
  is as follows:
  (a) Access status: should access be via deep-link only?
  (b) Hide other resources: Should other course resources be accessible?
  (c) In Contents + Gradebook: Should the resource (or folder) be listed in Course
      Contents and/or student's view of grades, when not accessed via deep link?
  (c) Access scope for link: Should access also be available to other resources in
      the same folder, and/or recursively into sub-folders, or just the one resource?
  (d) Link protection: should deep link launch only apply when accessed from a defined
      LTI Consumer, or from a link with a valid key?
  (e) Menus items displayed: Should the standard menu items in effect for the course
      be displayed in the header and footer, or should another menu collection apply?
  (f) Embedded: is the original launch context expected to be an iframe?  If so,
      "embedded" should be set so LON-CAPA will load other pages in the same iframe
  (g) Exit Button: Should a button be displayed at the right side of the header row? 
      (Left side has links to folder hierarchy for current resource/folder). Default
      text: "Exit Tool" is modifiable. Pushing the button will end the LON-CAPA
      session, and (optionally) redirect to a URL in the launch system.
  Note: users with "advanced privileges" for current role are exempt from 
  restrictions for (a), (b) and (c), and (e).
- Link protection can either be (a) mediated by LTI 1.1, or (b) (less securely) by
  using a "linkkey" sent as a key-value pair in POSTed data, or the query string.
  In the LTI case, if allowed by the domain, and if "Use identity" is set to "yes",
  and a LON-CAPA username is present in the LTI payload, authentication in LON-CAPA
  itself is not required, except for privileged users.
- Return of grades to the launcher system is available for resources or folders
  accessed via LTI-mediated deep link.
- A new course container type is available for delivery of Placement Tests.
  The characteristics of a placement test are as follows:
  (a) Each student may complete an instance of the test as many times as they wish.
  (b) There is no time limit for completion of an instance of the test.
  (c) Each student will receive a different randomization for each question each
  time they work on a new instance of the test.
  (d) A student's grades will be available for export for each instance of the test.
  On completion, a student's score on a placement test can be exported automatically 
  to system(s) outside LON-CAPA (customization by a sysadmin is required)
- External Tools defined by a Domain Coordinator can be available for import to a
  course, if the domain configuration permits it.
- External Tools can be defined by a Course Coordinator in a course, if the domain
  configuration permits it.
- Parameters available for each instance of an external tool differ depending on 
  whether the tool is set to be "gradable" (i.e., can receive scores from the tool).
- A shortcut to a student's view of a problem etc. is available from a 'View As' 
  item in the Functions menu above a problem.
- The Course Editor has a "Standard Problem" item (Grading tab) for creation of a
  new problem in a user's Authoring Space, or a course's own "Authoring Space".
- The Course Editor has an "Import from Course Resources" item (Import tab) to
  import published content from a course's own "Authoring" Space.
- Resources/Folders created in a course's own "Authoring" Space, then published, 
  have the following attributes:
  - course-only access rights apply.
  - the disk space quota for the course authoring space is shared with other 
    content uploaded directly to a course.
  - published content is only browsable in course context, and only in the course 
    to which it belongs.
  - published metadata are excluded from searchable metadata for a course's domain.
- Score upload form items support identification of a user based on clicker ID, for 
  those who prefer not to use LON-CAPA's in-built "Process Clicker" utility.
- Blocking communication/resource access (e.g., for exams) can include
  (a) suppression of interruptions to a student's workflow due to:
    (i) Critical messages not moved to INBOX.
    (ii) Detection of changes to course structure, as a result of actions by
         a Course Coordinator.
  (b) blocking student access to course grades via the "Grades" menu item, 
      and to a "detailed score sheet" if grading is set to use the Spreadsheet.
  (c) blocking student access to content search in course context.
  (d) blocking student access to "About Me" pages belonging to users in the course.
- Usage restriction for a particular slot can be for one or more folders
  and/or composite pages (in which case the slot may be used for all resources 
  within those map(s)).
- A unique mapalias can be set for a resource using the Course Editor, and the
  alias can be referred to in script blocks in problems in which one
  problem accesses a user's submissions etc. for another problem in the course.
- Map-level parameters can be set to apply recursively to subfolders.
   (a) Setting map-level parameters which apply recursively to subfolders is
       not permitted unless the course's homeserver is running 2.12; 
       hiddenresource and encrypturl are exempt, since they have always recursed.
   (b) Text in "Parameter in effect" cell in table mode includes "recursive"
       if parameter in effect is recursive for a map/folder. A link to display/set 
       the parameter is included if that item is not the enclosing map/folder.
- Resources or folders in the Supplemental Content area of a course can be 
  hidden/unhidden by a Course Coordinator using the Course Editor.
- Lenient (partial credit) parameter for optionresponse supports relative
  weights when checkboxes are in use.
  (a) Different numbers of points (either positive or negative) can be specified
      for correct foils (checked or unchecked) and incorrect foils (checked or
      unchecked).
  (b) Overview modes for parameter setting include textboxes for each of the
      four types if "weighted" is selected.
- Slots can now require each student to check-in from a unique IP address
  when using a particular slot for a specific resource. The IP address of
  the student's computer is then tied to that student's access to the resource
  thereafter, until the end date of the slot.
- Slots can support "deny from" specified IPs/Hosts as well as "allow from".
- Course settings > "Display of resources" can be used to set display of
  all External Resource Item as a link (with launch in a tab or window) 
  instead of in an iframe.
- Overview modes for parameter setting for Client IP/Name Access Control
  also include individual textboxes for each IP or Name, with separate
  boxes for "allow from" and "deny from".
- Time-Limit parameter ("interval") can include trailing "_done".
  Detection of release required includes 2.12 if interval parameter has
  trailing "_done".  Where present, a student can end a timed quiz/exam early
  by pushing a button (default text: "Done" can be changed).
- Reset access times helper used to reset timed quizzes/exams for specific
  students will delete student-specific interval parameter set if the "Done" 
  button was available and had been pushed.
- LON-CAPA as a LTI Provider:
  Course Coordinator can override domain defaults set in the Consumer
  definitions in the domain config. via Course Settings > LTI provider settings.
- Order of folders when using "Edit Resource Parameters - Overview Mode" now
  based on location in course instead of order by "realm".

Communication
- Files attached to LON-CAPA messages (normal or critical) will now be included 
  in the external email if the "Send copy to permanent e-mail address (if known)" 
  option is selected.  Attachments were previously only sent internally and 
  stripped from the external email.  

Grading
- When an instructor (or user with a custom role with rights to manage grades)
  has selected a role for a specific section, but currently has additional
  unexpired roles for other sections in the same course also with grading
  rights, bubblesheet grading will offer the option to grade for student IDs 
  matched in the bubblesheet data file for any of those sections.
- Student submission of files to externalresponse is supported; on submission
  a link to the file(s) in the portfolio space on the student's homseserver will 
  be sent to the external grader URL defined in the response item.
  (a) IP based-access for files submitted to externalresponse will be set
  automatically if the url attribute in the externalresponse tag begins
  http://machine.somewhere.toplevel (or https:// etc.), as long as the 
  "Submit entries below as answer to receive credit" radiobutton is checked.
  (b) IP-based access for grading server for portfolio files submitted
  to externalresponse will be revoked automatically following grading.
- Grading screens can be used to display "pass back" transactions, and
  for override of scores etc., for external tools set to be "gradable".
- If a problem has one or more parts with hand-graded item(s), i.e., those 
  for which "regrader" has been stored, LON-CAPA will display two dates/times 
  as the first items in the "Submissions" box, in cases where the date/time graded 
  is later than the date/time submitted:
  (a) Date Submitted
  (b) Date Graded

Printouts
- A printout icon is included in "Tools" above the "Course Contents" listing unless
  the course is empty. Options include:
  (a) print items not in a folder (i.e., in top level of course, if any exist)
  (b) print items in a selected folder
  Privileged users can also print a selected folder for selected users or CODEs.
- When displaying the list of resources from which to select for inclusion in 
  a printout, "Course Contents" (i.e., /adm/navmaps) items themselves are omitted.
- If enabled in a course, users can print problems as fillable PDF forms and upload 
  later for automated grading.

Authoring
- Functions menu when displaying/editing a file now includes Copy and Rename buttons.
- Schema documentation is added as a help item in "Edit XML" mode.
- Changes to directory listing display:
  (a) Shortcuts added to "Create a new directory or LON-CAPA document" box.
  (b) Actions for current directory" box removed and replaced with icons/links in 
      Functions menu below standard inline menus.
  (c) A quick name search box can be used to search for file(s) in Authoring Space 
      by file name, fragment of file name, or regular expression.
  (d) Links to editors for each problem in a directory listing are now: Edit, 
      Edit XML and Daxe. Links to editors for HTML files are now: Edit and Daxe.
- Common copyright/distribution options available when publishing a directory now
  include "public".
- Daxe is a resource editor for LON-CAPA files which uses an XML schema and Daxe 
  configuration to provide a complete editing environment for LON-CAPA resources.
- When in "Course Authoring" Space, "Import a File" and "Image" blocks in Edit
  mode include a "Choose File" link which allows selection of published files 
  from "Course Authoring" Space, or upload of a new file (with auto-publication).
- turnoffeditor" parameter previously available for formularesponse and
  mathresponse is now also available for customreponse, but default for
  formula and math is "no", whereas default for custom is "yes".

Domain Management
- Domain Configuration
  - Assignment of role in another domain to user's in your own domain can be set
    to require approval by (a) Domain Coordinator in user's domain, or (b) user
    who will be assigned the role, or can be disallowed.  (Default is allowed,
    with no approval required).  Different settings can apply depending on whether
    assigned role will be a domain, authoring space, course or community role.
  - Ability to set which types of user (e.g., Faculty etc.) may set their own 
    time zone to use when showing open dates. due dates etc.
  - Assignment of roles in different domain(s) to user's own domain can be set to:
    (a) Not allowed (b) User authorizes (c) Domain Coordinator authorizes, or
    (d) Unrestricted, for each of two categories of domain:
    (i) Other domain is for the same institution
    (ii) Other domain is for a different institution
  - Two new course container types: (a) Placement tests	and (b) LTI Provider
  - Placement Tests is new category in course catalog
  - Course/Community defaults which can be overridden in each course by a Coordinator
    include whether users can create/upload fillable PDF forms 
    (Acrobat Reader required).
 - Course/Community defaults which can be overridden in each course by a Domain 
    Coordinator include:
    (a) Student username in LTI launch of deep-linked URL accepted without 
        re-authentication
    (b) External Tools defined in the domain may be used in courses/communities
    (c) External Tools can be defined and configured in courses/communities
 - LON-CAPA as a Learning Tool Interoperability (LTI 1.1) Consumer:
   - External Tools (i.e., Providers) can be defined in a domain, for use in courses.
   - LON-CAPA can accommodate pass back of grades if the provider supports it.
   - Signature method, endpoint URL, user data sent on launch, and role mapping 
     from standard LON-CAPA roles to standard IMS roles are all configurable.
 - Domain status screen has link to show status of LON-CAPA SSL certificates.
   - Will display status of SSL key, certificate and revocation lists, as follows:
     (a) private key used with connections certificate
     (b) signed certificate used in establishing connections between LON-CAPA servers
     (c) signed client certificate used in making web requests for content replication
     (d) LONCAPA CA (Certificate Authority) cert
     (e) Certificate Revocations list
 - More granular control over SSL tunnel use for key exchange when initiating 
   connections to/from other LON-CAPA servers/VMs depending on whether they share 
   the same domain and/or institution. Options for SSL tunnel use can also be set 
   separately for outbound connections (lonc) and inbound connections (lond).  
   After making changes via the web GUI, the command:
   /home/httpd/perl/loncron --justreload 
   should be run (as www) from the command line
- Replication can use name-based virtual hosts with SSL, with verification of
  client certificate (cert: /home/httpd/lonCerts/lonhostnamecert.pem), signed
  by LON-CAPA CA, with Common Name of internal-<server hostname>, same IP address
  as server hostname
- Ability to set limits on the internal LON-CAPA commands which servers/VMs in 
   a domain may run when responding to data requests sent by LON-CAPA hosts at other 
   institutions.
- LON-CAPA as a Learning Tool Interoperability (LTI 1.1) Provider:
  - Can configure LTI-mediated deep-link only access to specific LON-CAPA folder(s) 
    or resource(s), via External Tool launch in a different learning management system.
  - Can configure basic LTI authentication, whereby a session can be established   
    in LON-CAPA (the LTI Provider) for users already logged into a different system 
    (the LTI Consumer), without re-authentication in LON-CAPA.
  To support these modes of operation the following can be set in a domain:
    (a) Encryption of shared secrets
    (b) Rules for shared secrets (min and max length and character requirements)
    (c) Definition of "Link Protectors" in a domain
    (d) Definition of supported LTI Consumers in a domain with the following options: 
      (i) Creation of new LON-CAPA user account available from an LTI Consumer.
      (ii) Creation of new LON-CAPA course available from an LTI Consumer.
      (iii) Self-enrollment in a LON-CAPA course available from an LTI Consumer.
      (iv) Support session expiration in LON-CAPA, after user logs out of LTI Consumer 
           which originally launched session, (if Consumer supports logoutServiceUrl
- Authentication types assignable to users include "lti", in which case login
  via LON-CAPA's standard login will be unavailable, and the user will only have
  access to LON-CAPA as an LTI Provider, with launch from another system.  The
  default authentication in a domain can be set to "lti".
- LON-CAPA as an LTI Provider can support the LTI Extension: Context Memberships 
  Service, whereby launch from the Consumer by a Course Coordinator can trigger  
  LON-CAPA to request a course roster from the Consumer.
- Command line script to create new SSL key and/or SSL certificate signing 
  requests (host cert and/or hostname cert):
  /home/httpd/lonCerts/manage_ssl_certs.pl
- "Pop-up if iframe" (Y/N) item added to options for dual SSO and non-SSO login 
  from /adm/login.
- URLs in direct links to LON-CAPA messages in notification email, and to
  publicly accessible syllabus or portfolio files can be set to use hostname
  of portal server instead of user's homeserver as first part of URL.

Documentation
- Additions to course coordination manual:
  (a) 'Menu display' and 'Link protection' items in Course Settings
  (b) Short URLs for deep-linking to a resource or folder in Course Editor
  (c) External Tools item added to "Link Content" section for Course Editor
- Additions to domain coordination manual:
  (a) Information about Domain Trust Settings
  (b) Description of configuration of External Tools (LON-CAPA as LTI Consumer)
  (c) Documentation for configuration of LON-CAPA as LTI Provider 

Third-party modules
- Update Geogebra to version 5.0.785.
- Update JSME to 2022-09-26 version.
- Update Jmol to version 16.1.13.
- Update CKeditor to version 4.21.0.
- Update jquery to 3.7.0; jquery-ui to 1.13

Other bug fixes
- More information is provided to privileged users if a map could not be loaded
  during course initialization because the file was missing.
- Hint to browsers to not autofill password field on proctor check-in page.
- If node switched to from load balancer can't connect to lond on user's
  homeserver, then session is switched to another node in the original list
  of usable nodes sent by the balancer.
- In course context, switch server to resource's home server opens new tab
  when editing published resource, and ca role is loaded,  when user's domain
  (by default) disallows session hosting of domain's users in resource's domain.
- For resources already checked into a slot (now past its end time),
  check for use of unique time periods in used slot, when checking for other
  reservable (future) slots.
- Print tables when "Allow problems to be split over pages" set to yes.
- Access to specific LON-CAPA message after login is supported in cases where a
  LON-CAPA loadbalancer node is used as the portal for a domain.
- Trust settings set in domain for:
  (a) "Co-author roles in this domain for others"
  (b) "Co-author roles for this domain's users elsewhere"
  taken into account when displaying "Switch Server" link to Authoring Space's 
  home server, and whether to check for ability to host a user on a remote server.
- Fixed a regression introduced in the course catalog in 2.11.4 for domains where 
  the instcode_format() routine in localenroll.pm had not yet been customized,
  whereby "No official courses to display" would be shown above a listing of 
  official courses, and the "Show more details" link for a course would be inactive.
- Eliminate javascript error when using "Select Community" link when Domain 
  Coordinator is cloning when using "Create a single community".
- Archive file (.zip, .tar etc.0  can be uploaded to top level of Main or 
  Supplemental Content, and contents can be extracted by a Course Coordinator.
- Support case where content is hidden and custom role can access Course Editor, 
  but "Advanced Role" at system level is not included for the role.
- When switching section for an existing student role no longer incorrectly
  log the context of the role expiration as "selfenroll".
- Create "empty" sequence file when copying an empty folder from Supplemental
  to Main Content using the Course Editor if original sequence file is absent
  to avoid "Map not found" warning on Course Initialization.
- When feedback on correctness is disabled and status is post-due date but 
  pre-answer date, "Answer submitted" is not shown in the Course Contents
  listing for the resource unless a submission has been made.
- Stop long parameter names overflowing category box in "Select Parameters
  to View" table row.
- When using "Edit Resource Parameters - Table Mode" no parameter setting
  table is displayed after "Update Display" pushed if User textbox contains
  a username or ID for a user not in the course.
- In Assessment Chart align " / maximum" in total (rightmost) column for students 
  with and without scores for selected folder(s), and 2 decimal places for maximum 
  for consistency with total scores.
- For user with a role of instructor in a course, display the Edit button in 
  the Functions menu for a published resource in a course, if user can edit it.
- TeXheight attribute (height in mm) in <img> tag will scale an image in a printout 
  when TeXwidth attribute is absent.
- Support height attribute in <displaystudentphoto /> tag when rendering student
  photo in a LON-CAPA resource for the web.

Internals
- Use cached names and cache user's 'About Me" page availability to speed up 
  display of discussion posts.
- Can use Server Name Indication (SNI) and SSL client certificate when replicating 
  content.
- Replaced use of LWP::UserAgent with LONCAPA::LWPReq so replication of
  content can include verification of the requesting server's client certificate 
  (Apache/SSL used).
- Cluster manager can push updated Certificate Revocation List (CRL) to cluster's 
  "name servers".
- The latest CRL is retrieved from a cluster's Certificate Authority by the
  nightly run of loncron.
- CRL checking is performed when creating the SSL channel used for key exchange 
  during negotiation of connection to remote lond.
- Checking for required LON-CAPA version accommodates parameter values which match 
  a regexp (currently for acc and lenient parameters) as well as designated values.
- A script is provided to create a Certificate Authority (CA) for a LON-CAPA cluster.
- Connection issues between offload node(s) and other nodes are handled gracefully
  when using a load balancer, by attempting to switch to other offload nodes and/or
  balancer(s).
- Storage and retrieval of data from GDBM files for domain, with namespaces
  beginning 'enc' use encryption when data are transferred.
- Implementation added for <lm> tag ("LON-CAPA Math")
- For multi-part problems containing perl script blocks inside part(s), if question 
  type = randomizetry, the first call to &random() for each part will set the new seed.
- <partorder> tag for a library file will include ids of any part tags; library file is 
  only loaded and inspected to check for parts if <partorder> is absent.
- Prepend /adm/wrapper for images, pdfs, and non-html documents included in
  folders in Supplemental Content area, so standard LON-CAPA menus, including
  breadcrumb trail will be shown above the resource.
- When displaying help files online (which use TtH) prevent inclusion of
  script tag for MathJax.js immediately after body tag.
- The value set for "Allow problems to be split over pages" can now be
  accessed within the &encapsulate_minipage() routine.
- A user's environment will be updated with access permission for all
  currently unhidden resources found in supplemental content in a course
  when a course role is selected.
- Changes made to supplemental content in a course by a Course Coordinator 
  will cause updates to access permissions for supplemental content in a user's
  environment for a user with a currently selected role in a course next:
  (a) displays Course Contents
  (b) displays Grades
  (c) uses LON-CAPA navigation arrows to move between course items
  (d) displays the contents of a folder in a course by clicking a link in
  the breadcrumbs trail above a rendered resource 
  if more than 10 minutes have elapsed since the last update check.
- Include resource identifier (symb) when checking access permission for resources 
  in a composite page to eliminate ambiguity for resources with multiple instances.

Discontinued functionality available in 2.11 and earlier
- The (optional) Remote Control interface component is no longer available.

Installation or update of a LON-CAPA instance
- For new installations, running ./UPDATE on a server/VM will prompt a system 
  administrator to create certificate signing requests (CSRs) for LON-CAPA SSL 
  certificates.
- Running ./UPDATE on a server/VM with existing LON-CAPA SSL certificates 
  will perform certificate checking:
  - Revoked or expired certs, or certs with an incorrect Common Name will be detected,
    and if a host cert or hostname cert is invalid, a check will be made for the
    existence of a valid CSR, and if so, the status of the CSR will be reported.
 - A system administrator can also create new SSL key and/or certificate signing 
   requests for:
  (a) LON-CAPA SSL certificates (Common Name is HostID) used for exchange of 
      cipher key via an SSL channel
  (b) Apache/SSL client certificate used for content replication between servers.
- Running ./UPDATE on an existing installation will retrieve: settings for 
  (a)Admin E-mail
  (b) Support E-mail
  (c) use of an SSL tunnel for key exchange when initiating LON-CAPA connection
  from the configuration.db on the domain's primary library server, if a Domain 
  Coordinator has set them.

Supported Linux Distributions
- Fedora 36, 37 and 38 added
- Ubuntu 22 added
- CentOS 9 stream added
- Red Hat 9, Oracle Linux 9, AlmaLinux 9, Rocky Linux 9 added

Specific enhancement requests/bugs addressed: (see http://bugs.loncapa.org)
2802, 2832, 4373, 4500, 4682, 4928, 5071, 5854, 5893, 5917, 5977, 6069, 6131, 
6215, 6400, 6581, 6598, 6656, 6690, 6694, 6698, 6723, 6754, 6763, 6777, 6808, 
6823, 6853, 6876, 6907, 6919, 6966, 6969, 6971, 6972, 6974, 6975, 6977, 6978, 
6979

Installation Notes:
 
To use this release you need to have version 1-34 of LONCAPA-prerequisites
installed.

To install this update:

1) You will need to be running CentOS 7; Scientific Linux 7;
RHEL 7, 8 or 9; Oracle Linux 7, 8 or 9; SLES 12, or 15; AlmaLinux 8 or 9,
Rocky Linux 8 or 9, Ubuntu LTS 14, 16, 18, 20 or 22; CentOS Stream 8 or 9, 
or Fedora 36-38.

(CentOS/Scientific Linux 5 and 6, SLES 10 and 11, Ubuntu LTS 12, Fedora 16-35, and
SuSE 13.1-13.2 should continue to work, but are deprecated).

You will need to be root to use the commands listed at steps 1(a) - 1(d) and
2 to 11 below. On Ubuntu LTS servers either prepend sudo for each command, or
use sudo -i.

To accompany the earlier 2.11.3 release, the GPG key for LON-CAPA's repositories
was updated to reflect modern standards.  If you are updating from LON-CAPA 2.11.2
or earlier, and have not already updated the GPG key, it is recommended to clear
cached packages previously downloaded from the LON-CAPA repository for your Linux
distro, before removing the old GPG key and importing the new one.

(a) You can display the currently installed LON-CAPA package signing GPG key 
as follows:

(i) CentOS/RHEL/Scientific Linux/Fedora/SLES
rpm -q gpg-pubkey --qf '%{VERSION}\t%{SUMMARY}\n' |grep LON

For CentOS/RHEL/Scientific Linux/Fedora/SLES the GPG key used in 2020 and earlier is:
155cf773    MSU LON-CAPA group (LON-CAPA installer) <[email-masked]>

For CentOS/RHEL/Scientific Linux/Fedora/SLES the GPG key used in 2021 and beyond is:
c11f2266    LONCAPA Academic Consortium (Package signing) <[email-masked]>

(ii) Ubuntu
sudo apt-key list

For Ubuntu the GPG key used in 2020 and earlier is:
155CF773    MSU LON-CAPA group (LON-CAPA installer) <[email-masked]>

For Ubuntu the GPG key used in 2021 and beyond is:
BF2CDADF    MSU LON-CAPA group (LON-CAPA installer) <[email-masked]>

(b) If you have a pre-2021 key clear the cache and import the new GPG key as follows:

(i) CentOS
yum clean all --disablerepo="*" --enablerepo=loncapa-updates-basearch --enablerepo=loncapa-updates-noarch
rpm -e gpg-pubkey-155cf773-431738a8
rpm --import 'http://install.loncapa.org/versions/centos/RPM-GPG-KEY-loncapa'

(ii) RHEL
yum clean all --disablerepo="*" --enablerepo=loncapa-updates-basearch --enablerepo=loncapa-updates-noarch
rpm -e gpg-pubkey-155cf773-431738a8
rpm --import 'http://install.loncapa.org/versions/redhat/RPM-GPG-KEY-loncapa'

(iii) Scientific Linux
yum clean all --disablerepo="*" --enablerepo=loncapa-updates-basearch --enablerepo=loncapa-updates-noarch
rpm -e gpg-pubkey-155cf773-431738a8
rpm --import 'http://install.loncapa.org/versions/scientific/RPM-GPG-KEY-loncapa'

(iv) SuSE/SLES
zypper refresh 'LON-CAPA'

(v) Ubuntu
sudo apt-key del 155CF773
sudo apt-get clean
wget -O ~/APT-GPG-KEY-loncapa.asc 'https://install.loncapa.org/versions/ubuntu/APT-GPG-KEY-loncapa.asc'
sudo apt-key add ~/APT-GPG-KEY-loncapa.asc

(vi) Fedora
yum clean all --disablerepo="*" --enablerepo=loncapa-updates-basearch --enablerepo=loncapa-updates-noarch
rpm -e gpg-pubkey-155cf773-431738a8
rpm --import 'http://install.loncapa.org/versions/fedora/RPM-GPG-KEY-loncapa'

(c) After you have imported the new key for 2021 (and beyond)

(i) CentOS/RHEL/Scientific Linux/Fedora/SLES/
rpm -q gpg-pubkey --qf '%{VERSION}\t%{SUMMARY}\n' |grep LON

will now report:
c11f2266   LONCAPA Academic Consortium (Package signing) <[email-masked]>

(ii) Ubuntu
sudo apt-key list

will now report:
BF2CDADF    MSU LON-CAPA group (LON-CAPA installer) <[email-masked]>

(d) The EPEL repository is now used by LON-CAPA for CentOS/RHEL/Scientific Linux
6 and 7 (64 bit only), and epel-release is a dependency in LONCAPA-prerequisites 1-34
for CentOS/Scientific Linux 6 and 7 (64 bit only).

On CentOS/Scientific Linux 7 to add the repo you can use:
yum install epel-release

For RHEL 7 use:
wget 'https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm'
yum install epel-release-latest-7.noarch.rpm

Note: if you are still running CentOS/Scientific Linux 6 (EOL was November 30 2020),
you would need to change the baseurl in /etc/yum.repos.d/epel.repo to point at:

https://archives.fedoraproject.org/pub/archive/epel/6/$basearch

and also change the baseurl in /etc/yum.repos.d/CentOS-Base.repo to point at:
http://vault.centos.org/6.10/os/$basearch/

That said you should update to a newer version of the distro as soon as you can.

If you are still running RHEL 6 (and have a subscription to the Extended Life Cycle Support
(ELS) Add-On, you would add the EPEL repo using:

wget 'https://archives.fedoraproject.org/pub/archive/epel/6/x86_64/epel-release-6-8.noarch.rpm'
yum install epel-release-6-8.noarch.rpm

and would then need to change the baseurl in /etc/yum.repos.d/epel.repo, as described above.

If you previously used EPEL but disabled it, by setting enabled=0 for [epel] in
/etc/yum.repos.d/epel.repo, use a text editor to change that to enabled=1.

2) Update LONCAPA-prerequisites to 1-34

(a) CentOS/RHEL/Oracle Linux/Rocky Linux/AlmaLinux 8 and 9

dnf update

(b) CentOS/RHEL/Scientific Linux/Oracle Linux 7 (or older_

yum update

Use:

yum repolist enabled 

to display currently enabled repos (which should include epel).

(c) SuSE/SLES

To refresh the LON-CAPA repository use:  zypper refresh -fdb
To update LONCAPA-prerequisites use: zypper update LONCAPA-prerequisites

(d) Ubuntu

sudo apt-get update
sudo apt-get upgrade

(e) Fedora 22 (and newer)

dnf update

(f) Fedora 21 (and older)

yum update

On all distributions, it is recommended that you check that you have
the correct version of LONCAPA-prerequisites installed before proceeding.

(i) CentOS/RHEL/Scientific Linux/Oracle Linux/Rocky Linux/AlmaLinux/
    Fedora/SLES/SuSE/
rpm -q LONCAPA-prerequisites

should report:
LONCAPA-prerequisites-1-34.X
(where X is a distro identifier e.g., centos7.lc)

(ii) Ubuntu
sudo dpkg -l loncapa-prerequisites

should report
ii loncapa-prerequisites 1.34-X
(where X is a version number which depends on Ubuntu distro)

Note: LONCAPA-prerequisites 1-26 for Red Hat/CentOS/Scientific Linux 
6 and 7 replaced the dependency on R with a dependency on R-core. 
Accordingly, for those distros, after updating to 1-34, from 1-25
or earlier you can use:

yum remove R R-core-devel R-devel R-java R-java-devel libMath-devel

and you can also use yum to remove java-1.8.0-openjdk and/or 
java-1.7.0-openjdk (which are R-java dependencies), unless you have
modified a standard LON-CAPA installation with packages which
themselves require java.

3) Download the new LON-CAPA tarball from
wget 'http://install.lon-capa.org/versions/loncapa-2.12.0.tar.gz'

and untar it:
tar xzvf loncapa-2.12.0.tar.gz

4) stop the LON-CAPA system services

RHEL/CentOS/Rocky Linux/AlmaLinux 8 & 9, Oracle Linux 7 - 9, Ubuntu 18 - 22, 
SLES15, Fedora 26 (and newer)

/home/httpd/perl/loncontrol stop

Other distros/versions:
/etc/init.d/loncontrol stop

5) stop the web server:

RHEL/CentOS/Oracle Linux/Rocky Linux/AlmaLinux/Scientific Linux 7 (and newer)
systemctl stop httpd

Fedora 17 (and newer)
service httpd stop

Fedora 16 (and older), RHEL/CentOS/Scientific Linux/Oracle Linux 6 (and older)
/etc/init.d/httpd stop

SLES15, Ubuntu 18 and newer
systemctl stop apache2

SuSE 13.X, SLES12
service apache2 stop

SLES 11, Ubuntu 16 and older
/etc/init.d/apache2 stop

6) Run the UPDATE script as root
(Note: you will be asked to confirm that you wish to remove files
installed by older versions of LON-CAPA which are no longer used by 2.12.0).

cd loncapa-2.12.0
./UPDATE

7) If you are updating a LON-CAPA library server from LON-CAPA version
2.10.1 or earlier, you will need to run a script to migrate Authoring 
Spaces in domain(s) hosted on the server from their old locations in:
/home/ to their new locations in /home/httpd/html/priv

To do this use the command:
perl /home/httpd/perl/debug/move_construction_spaces.pl move

Note: You can perform a dry-run, which will show what would happen, but will
not actually move anything, by omitting the "move" argument.

8) If your Apache web server has been configured to use SSL, and you have
included rewrite rules to rewrite all requests to http://<yourserver>/
to https://<yourserver>/ it is recommended you modify your rewrite rule to
(a) allow internal HEAD requests to /cgi-bin/mimetex.cgi to be served
http://, in order to support vertical alignment of mimetex images
(one of the options for rendering Math content); (b) allow requests
for certain URLs (external resource, annotations, and syllabus)
to be served http:// under certain conditions.

Starting with LON-CAPA 2.10, a config file containing rewrite
rules -- loncapa_rewrite.conf -- is added to /etc/httpd/conf
(CentOS, Red Hat, Scientific Linux, Oracle Linux, Rocky Linux,
AlmaLinux, Fedora) or /etc/apache2 (SLES, Ubuntu, Debian).
By default, rewrites are set to off (using RewriteEngine off).

If you already have you own rewrite rules in place for http -> https
you should either transfer them to loncapa_rewrite.conf, after
completing the LON-CAPA update, or leave your existing file in place 
and comment out the entries in loncapa_rewrite.conf. Otherwise, if you are 
using SSL with Apache, and would like requests to http://<yourserver>/
to be rewritten to https://<yourserver>/, you should copy
rewrites/loncapa_rewrite_on.conf to loncapa_rewrite.conf to enable this.
The rules included in that config file do not rewrite internal
requests (i.e., from 127.0.0.1) to https://, so vertical alignment
of mimetex images is supported. In 2.11 there are also rules to exclude
certain URLs from rewrites to https:// to avoid issues with 
mixed active content.

The 2.11.3 release included updates to rewrites/loncapa_rewrite_on.conf 
and rewrites/loncapa_rewrite_off.conf.  If you are updating from 2.11.2
or earlier and have customized loncapa_rewrite.conf then you should 
edit that file to incorporate the changes, which include addition of
this condition in a couple of places:

RewriteCond %{QUERY_STRING} (^|&(amp;|))usehttp=1($|&)

If you have not customized the file, then to enable rewrites, copy 
rewrites/loncapa_rewrite_on.conf to loncapa_rewrite.conf 
or copy rewrites/loncapa_rewrite_off.conf to loncapa_rewrite.conf 
to disable rewrites.

If your Apache configuration includes Strict-Transport-Security 
with max-age > 0, then http to https rewrites will apply for all URLs, 
so vertical alignment of mimetex images will not be supported, and 
browsers will block mixed active content for external resources and/or 
an external syllabus that uses http within an iframe on an https page.

Once you have the rules for ^/adm/wrapper/ext/(?!https:) and
^/public/.*/syllabus$ in place in loncapa_rewrite.conf, unless you use
Strict-Transport-Security you should also add the following to your 
<VirtualHost *:443> </VirtualHost> block, (the "*" might be:
 _default_ or an IP address or *):

<IfModule mod_rewrite.c>
  RewriteEngine on
  RewriteCond %{HTTPS} =on
  RewriteCond %{REQUEST_URI} ^/adm/wrapper/ext/(?!https:\/\/)
  RewriteCond %{QUERY_STRING} (^|&(|amp;))usehttp=1($|&)
  RewriteRule ^/adm/wrapper/ext/(?!https:\/\/) http://%{HTTP_HOST}%{REQUEST_URI} [R,L,NE]
  RewriteCond %{REMOTE_ADDR} 127.0.0.1
  RewriteRule (.*) - [L]
  RewriteCond %{REMOTE_ADDR} <Server IP>
  RewriteRule (.*) - [L]
  RewriteCond %{REQUEST_URI} ^/public/.*/syllabus$
  RewriteCond %{QUERY_STRING} (^|&(|amp;))usehttp=1($|&)
  RewriteRule ^/public/.*/syllabus$ http://%{HTTP_HOST}%{REQUEST_URI} [R,L,NE]
</IfModule>

replacing <Server IP> with the IP address of the server itself.

Note: this is only needed if you are using SSL (i.e., requests to
https://<yourserver>/ are supported) and you want to rewrite external
requests to http://<yourserver>/ to always use https://<yourserver>/
(with the exceptions noted above).

9) Note about /home/httpd/lib/perl/localenroll.pm
When you use UPDATE to update an existing LON-CAPA installation to a newer
version, the customizable localenroll.pm file is not overwritten.  This
is the file which must be customized to support integration of LON-CAPA
with institutional data sources (e.g., for automated update of course
rosters or user information). Whenever new routines are included in
localenroll.pm these will appear in localenroll-std.pm, which is updated
when a new LON-CAPA version is installed.

If you have previously customized localenroll.pm it is recommended that
you compare the contents of localenroll.pm and localenroll-std.pm after
an update to see if there are new subroutines (which exist as stubs in
localenroll-std.pm) which can be copied to your custom localenroll.pm,
and later customized, should you wish to use that functionality.

Recent additions to localenroll.pm included: (a) instsec_reformat(), used
to eliminate ambiguity in extraction of institutional section from
institutional course section, as used for automated enrollment, and when
compiling information shown for official courses in the course catalog,
(b) validate_crosslist_access(), used to check whether an official
course with the institutional code can have access to enrollment data
from a cross-listed institutional section code, given a co-owner, (c)
unamemap_rules() and unamemap_check() used to support authentication of
an alternate username, e.g., username entered in log-in page was email
address ([email-masked]) instead of just userid, (d) export_grades(),
which can be customized to push grade information for placement tests to 
some other gradebook, LCMS, or administrative system external to LON-CAPA.

10) restart the LON-CAPA system services:

RHEL/CentOS/Rocky/AlmaLinux 8 & 9, Oracle Linux 7 - 9, Ubuntu 18 - 22, SLES 15, 
Fedora 26 (and newer)
/home/httpd/perl/loncontrol start

Other distros/versions
/etc/init.d/loncontrol start

11) restart the webserver:

RHEL/CentOS/Oracle/Rocky/AlmaLinux/Scientific Linux 7 (and newer)
systemctl start httpd

Fedora (16 and older)/RHEL/CentOS/Scientific Linux 6 (and older)
/etc/init.d/httpd start

Fedora 17 (and newer)
service httpd start

SLES15/Ubuntu 18 (and newer)
systemctl start apache2

SuSE 12.X, 13.X, SLES12
service apache2 start

SuSE 11.X, SLES 11, Ubuntu 16 (and older)
/etc/init.d/apache2 start

12) It is recommended that loncron is run
(as the www user) after installation/update is complete.
(On Ubuntu LTS servers, first do: sudo -i )

su www
/home/httpd/perl/loncron

This will write to files in /home/httpd/lonTabs used to
store information about LON-CAPA versions on other servers in
the cluster to which the server belongs.  It may take some
minutes to complete as the script will contact other servers
in the LON-CAPA network sequentially.

13) It is also recommended that you check disk usage for courses
and Authoring Spaces, as 2.11 introduced default quotas of 0.5 GB
for each course (content uploaded directly via Course Editor) and
the same for each author.

For courses, log-in as Domain Coordinator and use:
Main Menu -> Status of domain servers -> Display quotas and usage for
Course/Community Content.

For Authoring Spaces, log-in as Domain Coordinator and use:
Main Menu -> Create users or modify the roles and privileges of users
->  Manage Users, and select Author in the "Role" dropdown, then
press the "Display List of Users" button.

The 0.5 GB default quota for Authoring Spaces in domain can be replaced via:
Main Menu -> Set domain configuration -> Blogs, personal web pages,
webDAV/quotas, portfolios

The 0.5 GB default quota for Courses can be replaced via:
Main Menu -> Set domain configuration -> Course/Community defaults

Quotas for individual authors can be set via:
Main Menu -> Create users or modify the roles and privileges of users
-> Add/Modify a User

Quotas for individual courses can be set via:
Main Menu -> View or modify a course or community
then search/select the course and use:
"View/Modify quotas for group portfolio files, and for uploaded content".

----NOTES
1) Defects reports, and enhancements requests can be entered at
         http://bugs.lon-capa.org
2) Mailing lists can be joined and left at http://mail.lon-capa.org
3) Installation/update support is available from helpdesk at loncapa.org

Stuart Raeburn
LON-CAPA Academic Consortium