{"id":23201661,"url":"https://github.com/mitodl/micromasters","last_synced_at":"2025-08-19T00:31:59.030Z","repository":{"id":5401550,"uuid":"52919185","full_name":"mitodl/micromasters","owner":"mitodl","description":"Portal for learners and course teams to access MITx Micromasters® programs ","archived":false,"fork":false,"pushed_at":"2024-04-12T17:47:31.000Z","size":39330,"stargazers_count":28,"open_issues_count":336,"forks_count":16,"subscribers_count":27,"default_branch":"master","last_synced_at":"2024-04-14T05:09:48.160Z","etag":null,"topics":["edx","micromasters","mitx"],"latest_commit_sha":null,"homepage":"https://mm.mit.edu","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mitodl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2016-03-01T23:53:17.000Z","updated_at":"2024-04-16T18:01:54.499Z","dependencies_parsed_at":"2023-09-22T00:51:41.235Z","dependency_job_id":"40e6520d-be2b-4dfd-a315-8dc272e92aae","html_url":"https://github.com/mitodl/micromasters","commit_stats":null,"previous_names":[],"tags_count":478,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitodl%2Fmicromasters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitodl%2Fmicromasters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitodl%2Fmicromasters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitodl%2Fmicromasters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mitodl","download_url":"https://codeload.github.com/mitodl/micromasters/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230292713,"owners_count":18203650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["edx","micromasters","mitx"],"created_at":"2024-12-18T15:16:38.043Z","updated_at":"2024-12-18T15:16:38.858Z","avatar_url":"https://github.com/mitodl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/mitodl/micromasters.svg?branch=master)](https://travis-ci.org/mitodl/micromasters) [![codecov](https://codecov.io/gh/mitodl/micromasters/branch/master/graph/badge.svg)](https://codecov.io/gh/mitodl/micromasters)\n\n# MicroMasters\nPortal for learners and course teams to access MITx MicroMasters programs.\n\n# Initial setup\n\nMicroMasters mostly follows the same [initial setup steps outlined in the common ODL web app guide](https://mitodl.github.io/handbook/how-to/common-web-app-guide.html).\nRun through those steps in order with the following changes:\n\n1. After [creating the database models](https://github.com/mitodl/handbook/blob/master/common-web-app-guide.md#3-create-database-tables-from-the-django-models), you should create the Opensearch indices via management command:\n\n   ```\n   docker-compose run web ./manage.py recreate_index\n   ```\n\n1. **Do not run the `createsuperuser` command.** When you log into this app via edX, a MicroMasters\nDjango user is created for you automatically. See the section below for instructions on how to run edX locally.\n\n\n### Running edX devstack locally _(optional, but recommended)_\n\nMicroMasters can work with a deployed instance of edX, but it's recommended that\nyou get it running locally. It's obviously more configurable that way, and you'll\nlikely need to run it locally for other projects in the future.\n\n#### 1) Install edX\nInstall edX following this guide https://github.com/mitodl/micromasters/blob/master/docs/configure_open_edx.md\n\n\n#### 2) Copy relevant values to use in the MicroMasters .env file\n\nThe MicroMasters codebase contains a ``.env.example`` file which will be used as\na template to create your ``.env`` file. For MicroMasters to work, it needs 4 values:\n\n- ``EDXORG_BASE_URL``\n\n    The base URL where the LMS server is running on your machine. This\n    _should_ typically be ``http://edx.odl.local:18000``.\n\n- ``EDXORG_CALLBACK_URL``\n\n    The callback URL from which MicroMasters will receive OAuth responses from the LMS server on your machine. This\n    _should_ typically be ``http://host.docker.internal:18000/``.\n\n- ``EDXORG_CLIENT_ID`` and ``EDXORG_CLIENT_SECRET``\n\n    These values can be found in the Django OAuth Toolkit Application you created [above](https://github.com/mitodl/micromasters/blob/master/docs/configure_open_edx.md).\n    **Client id:** and **Client secret:** values should be auto-generated for\n    that new Application. Use those values for the corresponding ``EDXORG_``\n    variables in the ``.env`` file.\n\n# Additional setup\n\n### Configure `.env` settings\n\nThe following settings should be configured before running the app:\n\n- `EDXORG_BASE_URL`, `EDXORG_CALLBACK_URL`, `EDXORG_CLIENT_ID` and `EDXORG_CLIENT_SECRET`\n\n    If you're running edX locally as detailed in the steps above, you've already done this. If you're running\n    against a deployed edX instance, `EDXORG_BASE_URL` and `EDXORG_CALLBACK_URL` should be the base URL of that instance, and you'll need to get the client id/secret values from devops.\n\n- `GOOGLE_API_KEY`\n\n    You should get your own API key from Google and use it here. [Learn how to\n    get an API key from Google.](https://github.com/mitodl/micromasters/blob/master/docs/google-api-key.md)\n\n\n# Running and Accessing the App\n\nMicroMasters follows the same steps outlined in the [common ODL web app guide for running and accessing the app](https://github.com/mitodl/handbook/blob/master/common-web-app-guide.md#running-and-accessing-the-app).\n\nAfter completing those steps, you should be able to do the following:\n\n1. Visit MicroMasters in your browser on port `8079`.\n2. Click \"Sign in with edX.org\" and sign in by authorizing an edX client. If you're\n running edX locally and you're not already logged in, use the same user that you configured above.\n\n### Configuration after first login\n\n**It's highly recommended that you do the following immediately after your first login with an edX user.**\nAfter logging into MicroMasters via edX with a given user for the first time, a new MicroMasters user is created to mirror that edX user.\nThese commands will help you to fully explore the MicroMasters UI:\n\n1. **Set your user as a superuser.**\n\n    Open django shell\n    ```\n    docker-compose run web bash\n    pyton manage.py shell\n    ```\n\n    Run below script in shell\n    ```python\n    from django.contrib.auth.models import User\n    # Replace 'staff' with the username of the edX user you logged in with\n    user = User.objects.get(username='staff')\n    user.is_superuser = True\n    user.is_staff = True\n    user.save()\n    ```\n\n2. **Seed the database with example programs, courses, users, etc.**\n\n   This will create programs and courses, and a set of users with enrollments and grades in those courses. This helps to flesh out\n   both the learner and instructor UX for the app.\n\n   ```bash\n   # Run from a shell in your host machine\n   # Replace 'staff' with the username of the edX user you logged in with\n   docker-compose run web ./manage.py seed_db --staff-user='staff'\n   ```\n\nAfter completing those two steps, reload MicroMasters in the browser and complete the profile for your user. You should be able to select a program for enrollment, and after completing the forms you should be able to access both the instructor and learner views (`/learners` and `/dashboard` respectively).\n\n### Wagtail CMS (Content Management System)\n\nThe CMS can be found at `/cms/`. Use the CMS to manage the content of the program pages and home page.\n\n#### Adding a new MicroMasters program\n\n1. Login to the CMS with an admin account. If you don't have one, you can use the superuser account created earlier.\n\n2. Click on the `Explorer` menu in the left nav to find the home page (labelled \"MIT credentials are...\")\n\n3. Click on `+ Add Child Page`\n\n4. Choose Program Page. Complete the form. Don't forget to publish your changes.\n\n#### Adding CMS users\n\n1. Don't create new users from the CMS. Ask users to log in and fill out a MicroMasters profile first.\n\n2. Login to the CMS with an existing account. If you don't have one, you can use the superuser account created earlier.\n\n3. From the Settings menu in the left nav, choose users.\n\n4. You can use the search box to locate users who already exist. If the user already exists, click on the username and\nskip to step 5.\n\n5. Click on the Roles tab.\n\n6. Check the box for the editors group. This will allow the user to view and edit all pages in the CMS.\n\n# Testing\n\nSee the ['Testing' section of the common web app guide](https://github.com/mitodl/handbook/blob/master/common-web-app-guide.md#testing) for most of the commands for running tests, linting, etc.\n\nThere are also some MicroMasters-specific testing tools:\n\n    # [Linux] Run JS type-checking\n    docker-compose run watch npm run flow\n    # [OSX] Run JS type-checking\n    npm run-script flow\n\nNote that running [`flow`](https://flowtype.org) may not work properly if your\nhost machine isn't running Linux. If you are using a Mac, you'll need to run\n`flow` on your host machine, like this:\n\n    yarn install --frozen-lockfile\n    npm run-script flow\n\n### Selenium\n\nTo run selenium tests make sure you have the application running, including the web\nserver and webpack dev server. Then run this script to run the selenium tests:\n\n    ./scripts/test/run_selenium_tests_dev.sh\n\nThis script sets up certain environment variables and runs\nall tests in the `selenium_tests/` directory, which are assumed\nto all require selenium.\n\n**Note**: If you are having trouble with database state\n(this works differently from the rest of the tests), remove the\n`--reuse-db` flag from `pytest.ini` and try again.\n\nIf a test errors but selenium is still working, it will take\na screenshot of the browser at the point of the error and write it\nas a png file in the project directory.\n\n##### Viewing running tests in the browser\n\nSelenium tests run locally will forward port 7000 to the inner container. To\nview the test server with your browser, go to `http://\u003cyour_mm_ip_address\u003e:7000`.\n\n\n# Running Commands\n\n#### Setting user state\n\nYou'll often need a user to be in a certain state with respect to some course/course run (e.g.: your user needs to have\na passing grade in some course). There is a management command that can be used to easily accomplish this kind of change\nof state.\n\n\t# See usage details\n    docker-compose run web ./manage.py alter_data --help\n    # See example commands\n    docker-compose run web ./manage.py alter_data examples\n\n#### Generating screenshots\n\nThere is a helper script that uses Selenium to create screenshots of various learner dashboard states.\nTo generate these screenshots, run this command:\n\n    ./scripts/test/run_snapshot_dashboard_states.sh\n\nScreenshots are saved to the `output` directory.\n\n#### Validating financial aid info\n\nTo validate prices and financial aid discounts for all programs run:\n\n    docker-compose run web ./manage.py validate_db\n\n\n# Connecting to external services\n\n#### Opensearch\n\nIf you want to connect to an ES cluster aside from the one created by Docker, you'll need to do the following:\n\n1. Add these variables to your `.env` file (without parentheses):\n\n        OPENSEARCH_INDEX=(your_index_name)\n        OPENSEARCH_URL=https://(your_open_search_url)\n        OPENSEARCH_HTTP_AUTH=(your_cluster_name):(key)\n\n2. If any of the above variables are set in the `web` configuration in `docker-compose.yml`, those\n will override the values you have in `.env`. Delete them.\n3. Restart the `db` and `opensearch-node1` docker-compose services if they're running:\n `docker-compose restart db opensearch-node1`\n\nYou should now be able to connect to the external ES cluster. You\ncan run `docker-compose run web ./manage.py recreate_index` to test\nthat it's working.\n\n\n# Electives\n#### Set up elective courses for a program\nIn django admin:\n1. Create an `ElectivesSet`, specify `Required number` which is a number of courses that a learner has to pick\nout of the courses in this set. (Multiple elective sets could be created for the same program)\n2. Create an `ElectiveCourse` object for each course that is going to be an elective.\n3. Update the `Program` object by setting the total number of courses required to\npass the program: `Num required courses`.\n\n\n## Session persistence issue\nIf you experience intermittent logouts while browsing the application and a general ephemeral behaviour from user sessions, switch the Django session backend by adding the following in your environment file:\n`SESSION_ENGINE=django.contrib.sessions.backends.file`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitodl%2Fmicromasters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitodl%2Fmicromasters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitodl%2Fmicromasters/lists"}