Repository navigation
docs: add multi-instance configuration guide - #521
Open
IvanStepanok wants to merge 18 commits into
Open
IvanStepanok wants to merge 18 commits into
IvanStepanok wants to merge 18 commits into
Conversation
Introduces Instance and InstancesConfig: what one Open edX platform is and how it is parsed from the INSTANCES block of the bundled config. Nothing reads it yet. Required fields are NAME, API_HOST_URL and OAUTH_CLIENT_ID; a malformed entry is dropped. KEY falls back to a slug of NAME, INSTANCE_NAME is localized with an English fallback, and PLATFORM_NAME defaults to the display name. The schema matches iOS (#672).
InstanceStore holds the instance catalog and the selected instance, persists the selection by key and publishes it as a StateFlow. A single-instance catalog selects its only instance automatically. Registered in Koin as InstanceStore and InstanceProvider; nothing consumes it yet. Mirrors iOS #673.
InstanceTheme derives a palette from an instance's accent color and its optional THEME.LIGHT/THEME.DARK overrides: only the fields an instance sets change, the rest keep the compiled default, and a missing dark value falls back to the light one. Palette field names are the ones iOS uses (#675), mapped onto AppColors. OpenEdXTheme observes InstanceThemeManager, which holds the selected instance's theme. Nothing applies a theme yet, so every screen still renders the default palette.
InstanceConfigLoader resolves the catalog the app runs with: the last cached remote catalog, else the bundled INSTANCES list, else nothing. A live fetch with at least one instance replaces that baseline and becomes the cache; a failed, malformed or empty response leaves it untouched. The catalog is fetched from INSTANCES_CATALOG_URL with a plain OkHttp client: no app interceptors, no credentials, a 10 second timeout. Remote snake_case keys are normalized with the same map iOS uses (#676). Nothing calls the loader at launch yet. Unlike iOS, the YAML build configuration stays: the Gradle build already turns it into the bundled config.json the loader reads.
InstanceHostInterceptor re-targets requests built against the app's base URL at the selected instance: scheme, host and port change, path and query stay. Other hosts, and every request made with nothing selected, pass through. Each request is tagged with the instance it was sent for. Token refresh calls the selected instance's /oauth2/access_token with its OAuth client. A 401 for a request sent before a site switch neither refreshes nor logs out, and tokens returned after the learner switched are discarded. The access token is only attached to requests for the active site's host. Mirrors iOS #677.
Preferences tied to a learner on one site (tokens, push token, user, profile, server app config, relative dates, calendar sync state) are now stored per instance, so switching sites can't leak one site's session into another. Device-wide settings (video quality, Wi-Fi only downloads, review prompt, What's New) stay shared. StorageNamespace decides where an instance's data lives. The instance whose API host and OAuth client match the app-level configuration keeps the existing unprefixed keys, so an upgraded single-site install stays signed in; that choice is recorded once and never re-derived from a later catalog. Every other instance gets instance.<key>.* keys. CorePreferences can now check or clear one instance's session without selecting it, and token refresh saves rotated tokens for the site that issued them even if the learner switched away mid-refresh. Mirrors iOS #678.
The refresh resolved the selected instance twice: once for the tokens and again for the endpoint, so a switch in between could send one site's refresh token to another. The instance is now resolved once per authenticate call and used for the tokens read, the token endpoint and where the result is saved. The minimum interval between refreshes is tracked per site, so refreshing one site no longer holds back another.
Each instance gets a Room database file of its own, so cached courses, offline progress, calendar state and download records can't collide between sites, even when both use the same course and block IDs. The legacy namespace keeps the original OpenEdX_db file, so an upgraded single-site install keeps its data with no schema migration and no destructive fallback. The injected DAOs now forward every call to the selected instance's database, resolved once per call; default @transaction methods are forwarded to the generated DAO, and flows switch databases after a site switch. Downloaded files go to instances/<site> under the downloads folder; the legacy namespace keeps the existing location. The download worker carries the site that queued it and writes each file's record to that site's database, so a download that finishes after a switch can't land in the other site. Once its own queue is empty it moves on to the selected site's queue. Progress and failure events reach the UI only for the selected site. Mirrors iOS #679.
The background sync read and cleared offline progress through the selected site's database, one call at a time, so a site switch in the middle could clear the other site's records and submit the rest to the wrong site. It now works in the database of the site it started on and stops before sending anything once another site is selected.
…hrough it InstanceSessionManager separates switching sites from signing out: - switchActiveInstance selects a site and applies its theme; nothing is torn down. - logoutCurrentInstance cancels downloads, unregisters push when wired, clears the site's tokens and user, then clears the selection. Cached courses and downloaded files stay, so signing back in to the same site is fast. - logout(instance) does that for the selected site and only clears the stored session of any other site. Both the Settings logout and the forced logout (401, disabled account) now go through logoutCurrentInstance instead of clearing preferences and every database table. Because logout keeps the cache, a different learner signing in to the same site would see the previous learner's cached courses; sign-in records who used the site last and clears the cached course data when that changes. Mirrors iOS #681.
- Signing out of a site with nothing queued no longer cancels the download worker, which may be working through another site's queue; removing downloads cancels the worker only when one of them was the active download. - Switching sites and signing out clear the web view session cookies, so the next web page fetches the selected site's cookies instead of trusting the previous site's freshness.
openedx-webhooks
added
open-source-contribution
|
Thanks for the pull request, @IvanStepanok! This repository is currently maintained by Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review. 🔘 Get product approvalIf you haven't already, check this list to see if your contribution needs to go through the product review process.
🔘 Provide contextTo help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:
🔘 Get a green buildIf one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green. DetailsWhere can I find more information?If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources: When can I expect my changes to be merged?Our goal is to get community contributions seen and reviewed as efficiently as possible. However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:
💡 As a result it may take up to several weeks or months to complete a review and merge your PR. |
These operations wait on the network, and a site switch while they wait used to send the rest of their work, and their results, to the newly selected site. - Requests can be pinned to a site: a RequestInstance tag set by the caller (Retrofit @tag) makes InstanceHostInterceptor send the request to that site's host and HeadersInterceptor attach that site's token, whichever site is selected by then. A site no longer in the catalog gets no token. - Sign-in pins its token, exchange and profile requests to the site it started on, writes tokens and user to that site's storage, and stops with InstanceSwitchedException, writing nothing, if another site was selected in the meantime. - Sign-out pins the revoke request and then signs out only the site it started on; if the learner switched meanwhile, the new site keeps its selection and session. Settings no longer cancels every download before signing out. - Push: the device token is device-wide again. PushRegistrations registers it with, and unregisters it from, one site at a time with pinned requests; signing out of any site, selected or not, unregisters that site first. Registration work is unique per site, and the token is rotated after sign-out only once no site is still signed in, since rotating would cut off the others. A new token is registered with every signed-in site.
IvanStepanok
force-pushed
the
docs/multi-instance-configuration
branch
2 times, most recently
from
October 19, 2026 21:43
fb581ec to
d2bab04
Compare
Signing out of the selected site waits on the network to unregister push. If the learner switched sites meanwhile, the rest of the sign-out read the selection again: it cleared the new site's session and reset its selection, cookies and theme. The site is now fixed when the sign-out starts. Only its session is cleared, and the selection, web cookies and theme are reset only while it is still the selected site.
The launch now waits for the instance catalog before showing the first screen: the splash screen stays up while InstanceConfigLoader resolves it (a live fetch with a 10 second timeout, falling back to the cached or bundled catalog), then the selected instance's theme is applied and routing proceeds. InstanceStore restores a saved selection synchronously from the cached catalog, so a process restored after death resolves the same site before any request is made. Config is now InstanceAwareConfig: for the keys an instance may override (API host, OAuth client, SSO URLs, token type, feedback email, FAQ, platform name, agreements, discovery, program, dashboard, course UI flags, SSO button title, experimental features and the login flags), a value the instance sets wins and everything else comes from the app-level config. Firebase, Braze, Branch, social providers, the URI scheme and app-wide feature flags stay app-level. Every existing Config consumer becomes instance-aware with no call-site changes. The app-level config stays available under its own Koin qualifier for what must not move with the selection: the Retrofit base URL that InstanceHostInterceptor rewrites, and the legacy storage owner check. Mirrors iOS #682, with the launch now awaiting the catalog as the final iOS behavior documented in #685.
Presentation layer for multi-instance support: choose, switch and sign out of learning sites, with each site's branding applied app-wide. - Learning Sites screen: the first screen of a multi-site build (Get Started) and, from Settings, where a learner switches sites. It lists the current site, other signed-in sites and the sites to add, with search and per-site log out. A signed-in site opens straight to its dashboard; any other opens its own sign-in. When switching, the previous site's screens are closed before the switch. - Sign In shows the selected site with a Change link. - Settings shows a Current Learning Site card, with Log Out folded into it. - Branding: the site's accent color across Compose screens and the tab bar, and its header background image and logo when configured. - Launch: a saved site without a session, or no site, starts at site selection; logout and forced logout return there. On the first launch after upgrading from a single-site build, the session that build had is opened on its site instead. - A catalog with one site hides all of it: same screens as before. Mirrors iOS #683.
Side-by-side screenshots against openedx-app-ios develop showed where the Android screens had drifted: - Settings: the current site card sits at the bottom, after Support, with Log out folded into it, as on iOS. - Learning Sites: the switching header shows the site's logo (the app logo when it has none) under the back button; the subtitle is secondary text; "No schools match your search" shows whenever nothing is left to add. - Logging out of a site uses the app's own log out dialog, now shared from core, instead of a plain alert. - Sign In shows the back arrow when reached from Learning Sites, and the selected site's logo when it has one. - Site rows show the host without the port, and use the iOS copy for the search placeholder and the empty result. - The Settings header follows the selected site's header background.
Signing out of a site waits on the network. A tap on another site in that time switched sites under the sign-out still running. Taps on a site, or on another sign-out, are now ignored until it finishes.
Documentation/Multi_Instance_Configuration.md: how multi-instance support behaves end to end, how data from a single-site install is carried over, and the key reference for both sources, the bundled INSTANCES list and the remote catalog with its snake_case key mapping. Mirrors iOS #685.
IvanStepanok
force-pushed
the
docs/multi-instance-configuration
branch
from
October 20, 2026 07:22
d2bab04 to
881ac3f
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
Documentation/Multi_Instance_Configuration.md: how multi-instance support works end to end on Android, and the full key reference for both config sources. Port of openedx-app-ios#685.INSTANCESlist inconfig.yaml, including which app-level keys an instance can overrideThe schema is shared with iOS, so one catalog can serve both apps. Stacked on #520.