Quickstart guide
This guide provides the instructions to set up the main accounts and services you need to use the Analytical Platform. Once you complete it, you can:
- access the Analytical Platform Control Panel
- explore data on the Analytical Platform
- begin developing your application in either JupyterLab or RStudio
- contribute to the Analytical Platform User Guidance
Before you begin
To use this guide, you need the following:
- a Ministry of Justice-issued Office 365 account
- a Ministry of Justice-issued laptop you can install apps on
- a mobile device you can install apps on
- access to the Justice Digital workspace on Slack
Complete this guide in order, following each step closely. If you encounter issues, preferably raise a ticket on GitHub issues
A member of the Analytical Platform team will contact you.
1. Read Terms of Use
For Analytical Platform best practice, you need to follow certain guidelines. Bookmark the following pages and ensure you follow them before you begin using the platform:
- Acceptable use policy: covers the way you should use the Analytical Platform and its associated tools and services
- Data and Analytical Services Directorate’s (DASD) coding standards: principles outlining how you should write and review code
- MoJ Analytical IT Tools Strategy: describes recommended ways of working on the Analytical Platform
2. Create Slack account
We use Slack to communicate status updates, such as scheduled maintenance for the Analytical Platform. You can also use it to communicate with our support team and the Analytical Platform user community.
There are two workspaces we recommend joining: Justice Digital and ASD. To join, while signed in to your work email, navigate to each workspace and request to join. Note that workspace moderators only consider users from the following email addresses:
- @justice.gsi.gov.uk
- @digital.justice.gov.uk
- @cjs.gsi.gov.uk
- @noms.gsi.gov.uk
- @legalaid.gsi.gov.uk
- @justice.gov.uk
- @judiciary.uk
Note: You can only access the Justice Digital and ASD workspaces using DOM1 and MoJ Digital and Technology MacBooks. If you use Quantum, you will need to access Slack using a mobile device instead.
Join Slack channels
Conversations in Slack are organised into channels, which each have a specific topic. After getting access to Slack workspace you need to separately join channels. Channels can be:
- public (all users can join) or
- private (users can only join by invitation) or
- be created based on teams, projects, locations, tools and techniques among others.
There are several public channels that are widely used and may be useful to join:
- the #analytical-platform-support channel is used for general discussion of the Analytical Platform – it is also monitored by the Analytical Platform team, who can help out with any technical queries or requests. Also used to request new or existing apps and app data sources
- the #ask-data-engineering channel is used for general discussion of data engineering and for getting in touch with the data engineering team with any technical queries or requests (such as airflow DAG reviews, database access, data discovery tool, etc).
- the #git, #r and #python channels can be used to get support from other users with any technical queries or questions – the #intro_r channel is aimed specifically at new users of R
- the #data_science channel is used for general discussion of data science tools and techniques
- the #general channel is used for any discussions that don’t fit anywhere else
- the #10sc channel can be used to get in touch with other people working at 10SC and to ask any questions about the building
There are lots of other channels you can join or you can set up a new one if you think something is missing. You may also wish to set up private channels to discuss specific projects and can direct message individual users.
3. Create GitHub account
Using your work email address (ending either justice.gov.uk or digital.justice.gov.uk), sign up for a GitHub account. See the GitHub documentation for instructions.
If you already have a GitHub account that you wish to use for work within the Ministry of Justice, you can use it provided you associate your work email address with the account in your user settings.
Ensure that:
- your account uses the free plan subscription
- you choose a username that does not contain upper-case characters (for good practice)
- you set your username to associate with your Git commits for every repository; see the GitHub documentation for instructions
- you follow the Ministry of Justice’s best practice guidelines when setting your password
- you configure two-factor authentication (2FA) on your mobile device; we recommend using either Google Authenticator or Microsoft Authenticator for 2FA
- For more information on 2FA within the Ministry of Justice, see the MoJ’s Security Guidance
4. Access the Analytical Platform
Once you have your GitHub account, there are two more steps to complete before you can access the Analytical Platform: joining the MoJ Analytical Services GitHub organisation and signing in to the Analytical Platform’s Control Panel.
Join MoJ Analytical Services
Please sign into the Analytical Platform GitHub Organisation using SSO, to get your GitHub account added to the Analytical Platform GitHub Organisation.
Sign in to the Control Panel
The main entry point to the Analytical Platform is the Control Panel. From there, you configure core tools such as JupyterLab, RStudio and Visual Studio Code. You log in to the Control Panel using your GitHub account.
When accessing the Control Panel for the first time you will be prompted to authenticate with your Justice account. You only need to do this once, and will not see this on subsequent logins.
Get Athena Access
Many users of the Analytical Platform wish to query our databases using Amazon Athena. We manage access to our databases via the Data-Engineering-Database-Access repository. In order to get access to Athena, you will need to have your alpha_user_
name added to the Standard Access list. To do this, raise a PR, and post it in #ask-data-engineering on Slack to get it approved by one of our Data Engineers. Once this PR has been merged, your account will be given access to Athena and a selection of non-sensative datasets. For more information, including how to request access to specific databases via Projects
, please refer to the README for Database Access.
5. Set up JupyterLab
Note: Only follow this step if you want to use the Analytical Platform as a Python-based user. If you want to use R instead, proceed to step 6 to configure RStudio instead.
If you want to build and deploy applications on the Analytical Platform using Python, you need to set up JupyterLab, the Python-based IDE (Integrated Development Environment) on the Analytical Platform.
To set up JupyterLab, navigate to the Control Panel. Under Jupyter Lab Data Science [Git extension], use the drop-down menu to select the version of JupyterLab you want to deploy. Unless you need to use a specific version, we recommend selecting the first option in the list. This will deploy JupyterLab on a virtual machine in your browser, with all of the required components it requires to run.
Create and add JupyterLab SSH key to GitHub
To access GitHub repositories from JupyterLab, you need an SSH key to enable secure communication and authentication between the two services. Do not try to use an existing SSH key; each tool you use requires a unique key.
To create an SSH key in JupyterLab:
- Open JupyerLab from the Analytical Platform Control Panel
- Select the + icon in the file browser to open a new Launcher tab
- Navigate to the Other section and select Terminal
- Run the following command in your terminal, replacing your_email@example.com with the email address you used to sign up for GitHub:
$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
- The response will ask you to choose a directory to save the key in; press Enter to accept the default location
- The response will also ask you to set a passphrase; press Enter to not set a passphrase.
- To view the SSH key, run:
$ cat /home/jovyan/.ssh/id_rsa.pub
- Copy the SSH key to your clipboard
You then need to add the SSH key to GitHub; see the GitHub documentation for instructions.
6. Set up RStudio
Note: Only follow this step if you want to use the Analytical Platform as an R-based user. RStudio supports Python, but we recommend using JupyterLab for Python instead. If you configured JupyterLab in the previous step, proceed to step 7.
If you want to build and deploy applications on the Analytical Platform using R, you need to set up RStudio, the R-based IDE (Integrated Development Environment) the Analytical Platform provides.
To set up RStudio, navigate to the Control Panel. Under RStudio, use the drop-down menu to select the version of RStudio you want to deploy. Unless you need to use a specific version, we recommend selecting the first option in the list. This will deploy RStudio on a virtual machine in your browser, with all of the required components it requires to run.
Create and add RStudio SSH key to GitHub
So you can access GitHub repositories from RStudio, you need an SSH key to connect the two. Do not try to use an existing SSH key; each tool you use requires a unique key.
To create an SSH key in RStudio:
- Open RStudio from the Analytical Platform Control Panel
- Navigate to Tools>Global Options
- In the Options window, select Git/SVN in the navigation menu
- Select Create RSA key and then Create
- When the Information window appears, select Close
- Select View public key and copy the SSH key to your clipboard
You then need to add the SSH key to GitHub; see the GitHub documentation for instructions.
Now that you have completed this guide you are ready to begin using the Analytical Platform. See training for a list of different resources to help you begin using the platform.
7. Set up Visual Studio Code
Note: Visual Studio Code is a general purpose code editor, therefore it might not have all the capabilities you’d expect from JupyterLab or RStudio.
To set up Visual Studio Code, navigate to the Control Panel. Under Visual Studio Code, use the drop-down menu to select the version of Visual Studio Code you want to deploy. Currently there is only one release.
Create and add Visual Studio Code SSH key to GitHub
To access GitHub repositories from Visual Studio Code, you need an SSH key to enable secure communication and authentication between the two services. Do not try to use an existing SSH key; each tool you use requires a unique key.
To create an SSH key in Visual Studio Code:
- Open Visual Studio Code from the Analytical Platform Control Panel
- Open a new terminal, and run the following commands
$ ssh-keygen -t ed25519 -C "<your email address>"
- The response will ask you to choose a directory to save the key in; press Enter to accept the default location
- The response will also ask you to set a passphrase; press Enter to not set a passphrase.
- To view the SSH key, run:
$ cat ~/.ssh/id_ed25519.pub
- Copy the SSH key to your clipboard
You then need to add the SSH key to GitHub; see the GitHub documentation for instructions.