diff --git a/step_by_step_installation_guide.md b/step_by_step_installation_guide.md new file mode 100644 index 0000000000000000000000000000000000000000..d16c128277a2650cbc518d09bde2e9046c0649ac --- /dev/null +++ b/step_by_step_installation_guide.md @@ -0,0 +1,246 @@ +# Step-by-Step Installation Guide + +### Prerequisite: Access to Repos and Documentation +Ensure you have read access to the following repositories: + +- **Frontend**: [Frontend GitLab Repo](https://transfer.hft-stuttgart.de/gitlab/HFTSoftwareProject/moodledta) +- **Backend**: [Backend GitLab Repo](https://transfer.hft-stuttgart.de/gitlab/HFTSoftwareProject/dtabackend) +- **Test Runner**: [Test Runner GitLab Repo](https://transfer.hft-stuttgart.de/gitlab/HFTSoftwareProject/dtatestrunner) + +### Prerequisite: Infra Downloads (VirtualBox & Ubuntu 22.04 LTS Desktop) +Download and install the following: + +- [VirtualBox 7.0.14](https://download.virtualbox.org/virtualbox/7.0.14/VirtualBox-7.0.14-161095-Win.exe) +- [Ubuntu 22.04 LTS Desktop ISO](https://ubuntu.com/download/desktop/thank-you?version=22.04.3&architecture=amd64) + +--- + +## Host Installation + +1. Install **VirtualBox**. +2. [Optional] Install VirtualBox Guest Additions for better integration. + +--- + +## Virtual Machine (VM) Installation + +1. **Create a new VM** in VirtualBox with the following settings: + - **CPU**: 2 CPUs x 1 Core + - **RAM**: 4 GB + - **HDD**: 40 GB + - **Network**: Default settings + - **ISO Image**: Use the downloaded Ubuntu 22.04 LTS Desktop ISO + +2. **Start the VM** and proceed with the installation: + - Choose `Install Ubuntu`. + - Select `Minimal Installation`. + - Accept default settings. + - Create a user (use your initials or a username of choice). + +--- + +## Inside Ubuntu 22.04 LTS Desktop (Minimal Installation Setup) + +1. Update the package list: + ```bash + sudo apt update + ``` + +2. Install required packages: + ```bash + sudo apt install git openjdk-17-jdk maven docker.io docker-compose + ``` + +3. Download and install **Eclipse IDE**: + - Download: [Eclipse IDE for Java EE Developers](https://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/2023-12/R/eclipse-jee-2023-12-R-linux-gtk-x86_64.tar.gz) + - Create an Eclipse directory: + ```bash + sudo mkdir /opt/eclipse + sudo chown root:docker /opt/eclipse + ``` + - Unpack the downloaded file: + ```bash + sudo tar xvzf ~/Downloads/eclipse-jee-2023-12-R-linux-gtk-x86_64.tar.gz -C /opt/eclipse + ``` + - Create a symbolic link for Eclipse: + ```bash + sudo ln -s /opt/eclipse/eclipse /usr/local/bin/eclipse + ``` + +--- + +## Loading Assets + +1. Create a development directory and clone the repositories: + ```bash + mkdir ~/dev + cd ~/dev + git clone <repository_url> + ``` + +2. Start Eclipse: + - Create a new workspace under `~/dev`. + - Ensure `.gitignore` includes Eclipse project files. + +3. Import the Maven projects from the file system into Eclipse. + +4. If necessary, create a local Maven repository by following the documentation in the backend repository. + +5. Add a dependency for `unifiedticketing`: + ```bash + mvn deploy:deploy-file -DgroupId=de.hftstuttgart -DartifactId=unified-ticketing -Dversion=0.2.2 -Durl=file:./local-maven-repo/ -DrepositoryId=local-maven-repo -DupdateReleaseInfo=true -Dfile=./local-maven-repo/unified-ticketing-0.2.2.jar + ``` + +--- + +## Docker Setup + +1. Create and configure a Docker Compose environment: + - Copy the `docker-compose.yaml` file from the repository. + - Spin up the services using: + ```bash + docker-compose up -d + ``` + +2. After starting **Moodle**: + - Install the DTA plugin. + - Configure Moodle to open the necessary ports and hosts: + - **Site Administration** > **Security** > **HTTP Security**. + - Set the DTA plugin backend URL to the Docker service name (e.g., `cahcedta:8080`). + +3. Ensure read/write access to the host temp directory for the DTA plugin: + ```bash + sudo chown root:docker /tmp/dta-tests + ``` + +4. Configure Moodle: + - Create a new course. + - Add a new assignment. + - Set the assignment as **Dockerized Test Agent**. + - Provide the example repo in `teacher-dta-dir.txt`. + +5. Add a submission and provide the example repo in `student-dir.txt`. + +--- + +## Pushing Results + +1. Create accounts: + - [GitLab Account](https://transfer.hft-stuttgart.de/gitlab) (HFT Transfer) + - [DockerHub Account](https://hub.docker.com/) + +2. Add your accounts to the necessary groups in GitLab. + +3. Create a Gitlab Access Token + To authenticate with GitLab, you will need to create a **Personal Access Token**. Follow these steps: + + 1. Log in to your GitLab account. + 2. Navigate to the **User Settings** by clicking on your profile icon in the top-right corner. + 3. Under **Access Tokens**, create a new token: + - **Name**: Choose a descriptive name (e.g., `GitLab Access Token`). + - **Scopes**: Select the appropriate scopes. For typical git operations, you will need: + - `api` + - `read_repository` + - `write_repository` + - **Expiration Date**: Set an expiration date (optional but recommended). + 4. Click **Create Access Token** and save it securely. **This is the only time the token will be shown**. + +4. Configure Git to Use the Access Token +Now that you have the access token, configure git to use it for authentication. Open a terminal and follow these steps: + + 1. **Cache Git Credentials** (to avoid entering the token multiple times): + ```bash + git config --global credential.helper cache + ``` + This will cache your credentials for a short period of time. + + 2. **Set your Git Username**: + ```bash + git config --global user.name "<your_name>" + ``` + Replace `<your_name>` with your GitLab username. + + 3. **Set your Git Email**: + ```bash + git config --global user.email "<your_email>" + ``` + Replace `<your_email>` with the email associated with your GitLab account. + + 4. **Verify the Git Configuration**: + To check the configuration settings you just applied, use: + ```bash + git config -l + ``` + This command will list all the global configurations for git. + +5. **Use the Access Token** for Git Operations: + When you perform a git operation (such as `git clone`, `git pull`, or `git push`) that requires authentication, Git will prompt you for a username and password. Use the following: + - **Username**: Your GitLab username or email. + - **Password**: Paste the Personal Access Token you created earlier. + + Git will then authenticate using the access token. + + +3. Push your results: + - Always pull before pushing: + ```bash + git pull + ``` + - In case of conflicts: + ```bash + git merge + ``` + - Push your changes: + ```bash + git push + ``` + - Push the Docker image: + ```bash + docker push <image> + ``` + +--- + +## Running the Application + +1. Create a directory for the **modta**: + ```bash + mkdir ~/modta + cp -R ~/dev/dtabackend/ifc/generic-proxy/ ~/modta + ``` + +2. Set up the environment: + ```bash + sudo mkdir /tmp/dta-tests + sudo chown root:docker /tmp/dta-tests + export EGID=$(getent group docker | cut -d: -f3) + cd ~/modta + docker-compose up -d + ``` + +3. Check if the containers are running successfully: + ```bash + docker container ls + ``` + +--- + +## Application Setup + +1. **Moodle Installation**: + - Follow the Moodle documentation in the frontend repository: [Moodle DTA Docs](https://transfer.hft-stuttgart.de/gitlab/HFTSoftwareProject/moodledta). + +2. **Testing**: + - See the testing documentation in the backend repository: [Backend Test Docs](https://transfer.hft-stuttgart.de/gitlab/HFTSoftwareProject/dtabackend). + +3. **View Logs**: + ```bash + docker logs -f <container_name> + ``` + +4. **Stop Services**: + ```bash + docker-compose down + ``` + +---