diff --git a/README.md b/README.md index b3c6df1e44057950d5c958d1ae706a6789109303..4a2339faadd00087409a15af25d59fee2a51f9ce 100644 --- a/README.md +++ b/README.md @@ -2,67 +2,102 @@ ## Getting started -*Reclaim: This tutorials is written for Ubuntu users.* +*Pre-require: Ubuntu Terminal* Tutorial source: - [How to run Java Hello World in Docker](https://youtu.be/zORBzMiBjRI?si=8f_Y0b56jfU0HxGi) -- [Create, manage and deploy DevContainers](https://gitlab.lis-lab.fr/thi-phuong.kieu/devcontainer_formation/-/blob/main/training/dcli_training.md) +- [Create, manage and deploy DevContainers](https://gitlab.lis-lab.fr/thi-phuong.kieu/devcontainer_formation/-/blob/main/training/dcli_training.md)- [Docker Installation Guildline](https://docs.docker.com/engine/install/ubuntu/) ## Step by step ### Installation -#### Eclipse IDE +#### Install Docker -1. Download the installer [here](https://www.eclipse.org/downloads/packages/installer). -2. Extract the archive file, e.g. the 64-bit version: +1. Uninstalling any potential conflicting packages already installed on your computer: ```bash - tar xf eclipse-inst-linux64.tar.gz + for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done ``` -3. Run the installer: + +2. Set up Docker's apt repository: ```bash - cd eclipse-installer - ./eclipse-inst # or sudo ./eclipse-inst + # Add Docker's official GPG key: + sudo apt-get update + sudo apt-get install ca-certificates curl + sudo install -m 0755 -d /etc/apt/keyrings + sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc + sudo chmod a+r /etc/apt/keyrings/docker.asc + + # Add the repository to Apt sources: + echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ + $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + sudo apt-get update ``` -#### DCLI - -[Installation Guildline](https://gitlab.lis-lab.fr/thi-phuong.kieu/devcontainer_formation/-/blob/main/ubuntu.md) - -#### Docker - -[Installation Guildline](https://docs.docker.com/engine/install/ubuntu/) - -### Import Java Project - -Open Eclipse, create your own project or import the devs-dclitest project [here](https://gitlab.lis-lab.fr/thi-phuong.kieu/devs-dclitest/-/blob/main/devs-dclitest.zip). +3. Install the Docker packages: + ```bash + sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin + ``` -### Install Eclipse Docker Tooling +4. Configure docker in rootless mode + ```bash + sudo groupadd docker + sudo usermod -aG docker $USER + ``` -**Option 1: Download from the Eclipse Marketplace** +5. Verify that the installation is successful by running the hello-world image: + ```bash + docker run hello-world + ``` + This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits. + ```txt + Hello from Docker! + This message shows that your installation appears to be working correctly. + ... + ``` -1. Go to *Help* → *Eclipse Marketplace...* +#### Install Squashfs tools -2. Search for *Docker Tooling* then click *Install*. +```bash +sudo apt-get update && sudo apt-get install squashfs-tools +``` +#### Install Devcontainer Command Line Interface (DCLI) +DCLI is a tool which will help you manage DevContainers (https://gitlab.lis-lab.fr/sicomp/dcli) -**Option 2: Download manually** +1. If you don't already have git installed, type: + ```bash + sudo apt install git + ``` -If unsuccessfully, install manually follow these steps: +2. Once done clone the DCLI directory: + ```bash + git clone https://gitlab.lis-lab.fr/sicomp/dcli + ``` -1. Go to *Help* → *Install New Software...* +3. Proceed to the install: + ```bash + cd dcli + chmod +x install.sh + ./install.sh + ``` -2. Click *Add...* +4. Once installation is complete, you have to source your bashrc: + ```bash + source ~/.bashrc + ``` -3. Enter the following: +5. Check that dcli is working properly by typing: + ```bash + dcli --version + ``` - - Name: Eclipse Docker - - - Location: https://download.eclipse.org/linuxtools/update-docker/ +### Import Java Project - Then click *Add*. +Open Eclipse, create your own project or import the devs-dclitest project [here](https://gitlab.lis-lab.fr/thi-phuong.kieu/devs-dclitest/-/blob/main/devs-dclitest.zip). -4. Check the Docker Tooling option and install. ### Write Dockerfile script @@ -82,45 +117,7 @@ CMD ["java", "-cp", "/devs-dclitest/bin:/devs-dclitest/lib/fwkdevs-v0.7", "Simul ### Create docker image -Right click to *Dockerfile* → *Run As* → *Docker Image Build*. - - - -Write *Image Name*, e.g. *devs-dcli:test*. - -Wait for the image built succesfully. -E.g. Build process of image devs-dcli:test -```bash -Step 1/8 : FROM openjdk:17 - ---> 5e28ba2b4cdb -Step 2/8 : COPY src/ /devs-dclitest/src/ - ---> 0decf775c2d8 -Step 3/8 : COPY lib/ /devs-dclitest/lib/ - ---> 1c9d49d80b7f -Step 4/8 : WORKDIR /devs-dclitest - ---> Running in 091fd0917dfd - ---> 8c3614e1d136 -Step 5/8 : RUN mkdir -p /devs-dclitest/bin - ---> Running in f5a5ce7416d8 - ---> 81ac429c3dd0 -Step 6/8 : RUN javac -cp "/devs-dclitest/lib/fwkdevs-v0.7" -d /devs-dclitest/bin /devs-dclitest/src/*.java - ---> Running in 1ed5149e6b28 -Note: /devs-dclitest/src/Car.java uses unchecked or unsafe operations. -Note: Recompile with -Xlint:unchecked for details. ----> 25fbba4dacc8 -Step 7/8 : WORKDIR /devs-dclitest/bin - ---> Running in 451e735c007d - ---> 54a5fb214664 -Step 8/8 : CMD ["java", "-cp", "/devs-dclitest/bin:/devs-dclitest/lib/fwkdevs-v0.7", "Simulator"] - ---> Running in b287512ceb80 - ---> 530f80b5391d -Successfully built 530f80b5391d -Successfully tagged devs-dcli:test -``` -If successfully, right click on the main class, then *Run As* → *Java Application in Container*. - - -**Note:** In case Docker Tooling has some problems, install Docker on Ubuntu (follow guildlines [here](https://docs.docker.com/engine/install/ubuntu/)). Then build and run docker by command line: +Then build and run docker by command line: ```bash docker build -t devs-dcli:test . @@ -158,8 +155,6 @@ You will see the VSCode workspace opened. Test running the java program inside t java -cp /devs-dclitest/bin:/devs-dclitest/lib/fwkdevs-v0.7 Simulator ``` - - Stop the container: ```bash @@ -205,7 +200,7 @@ On the second window, type: dcli config ``` -```bash +```txt Please provide the following information to create the .cluster_config file. Cluster server name/address [sms]: sms LIS cluster username []: your-user.name diff --git a/README_oldversion.md b/README_oldversion.md new file mode 100644 index 0000000000000000000000000000000000000000..b3c6df1e44057950d5c958d1ae706a6789109303 --- /dev/null +++ b/README_oldversion.md @@ -0,0 +1,250 @@ +# How to run a Java program in DevContainer on the LIS Cluster + +## Getting started + +*Reclaim: This tutorials is written for Ubuntu users.* + +Tutorial source: +- [How to run Java Hello World in Docker](https://youtu.be/zORBzMiBjRI?si=8f_Y0b56jfU0HxGi) +- [Create, manage and deploy DevContainers](https://gitlab.lis-lab.fr/thi-phuong.kieu/devcontainer_formation/-/blob/main/training/dcli_training.md) + +## Step by step + +### Installation + +#### Eclipse IDE + +1. Download the installer [here](https://www.eclipse.org/downloads/packages/installer). +2. Extract the archive file, e.g. the 64-bit version: + ```bash + tar xf eclipse-inst-linux64.tar.gz + ``` +3. Run the installer: + ```bash + cd eclipse-installer + ./eclipse-inst # or sudo ./eclipse-inst + ``` + +#### DCLI + +[Installation Guildline](https://gitlab.lis-lab.fr/thi-phuong.kieu/devcontainer_formation/-/blob/main/ubuntu.md) + +#### Docker + +[Installation Guildline](https://docs.docker.com/engine/install/ubuntu/) + +### Import Java Project + +Open Eclipse, create your own project or import the devs-dclitest project [here](https://gitlab.lis-lab.fr/thi-phuong.kieu/devs-dclitest/-/blob/main/devs-dclitest.zip). + +### Install Eclipse Docker Tooling + +**Option 1: Download from the Eclipse Marketplace** + +1. Go to *Help* → *Eclipse Marketplace...* + +2. Search for *Docker Tooling* then click *Install*. + + +**Option 2: Download manually** + +If unsuccessfully, install manually follow these steps: + +1. Go to *Help* → *Install New Software...* + +2. Click *Add...* + +3. Enter the following: + + - Name: Eclipse Docker + + - Location: https://download.eclipse.org/linuxtools/update-docker/ + + Then click *Add*. + +4. Check the Docker Tooling option and install. + +### Write Dockerfile script + +Create and file named *Dockerfile* under the project folder, and insert this script: + +```javascript +FROM openjdk:17 +COPY src/ /devs-dclitest/src/ +COPY lib/ /devs-dclitest/lib/ +COPY input/ /devs-dclitest/input/ +COPY output/ /devs-dclitest/output/ +WORKDIR /devs-dclitest +RUN mkdir -p /devs-dclitest/bin +RUN javac -cp "/devs-dclitest/lib/fwkdevs-v0.7" -d /devs-dclitest/bin /devs-dclitest/src/*.java +CMD ["java", "-cp", "/devs-dclitest/bin:/devs-dclitest/lib/fwkdevs-v0.7", "Simulator"] +``` + +### Create docker image + +Right click to *Dockerfile* → *Run As* → *Docker Image Build*. + + + +Write *Image Name*, e.g. *devs-dcli:test*. + +Wait for the image built succesfully. +E.g. Build process of image devs-dcli:test +```bash +Step 1/8 : FROM openjdk:17 + ---> 5e28ba2b4cdb +Step 2/8 : COPY src/ /devs-dclitest/src/ + ---> 0decf775c2d8 +Step 3/8 : COPY lib/ /devs-dclitest/lib/ + ---> 1c9d49d80b7f +Step 4/8 : WORKDIR /devs-dclitest + ---> Running in 091fd0917dfd + ---> 8c3614e1d136 +Step 5/8 : RUN mkdir -p /devs-dclitest/bin + ---> Running in f5a5ce7416d8 + ---> 81ac429c3dd0 +Step 6/8 : RUN javac -cp "/devs-dclitest/lib/fwkdevs-v0.7" -d /devs-dclitest/bin /devs-dclitest/src/*.java + ---> Running in 1ed5149e6b28 +Note: /devs-dclitest/src/Car.java uses unchecked or unsafe operations. +Note: Recompile with -Xlint:unchecked for details. +---> 25fbba4dacc8 +Step 7/8 : WORKDIR /devs-dclitest/bin + ---> Running in 451e735c007d + ---> 54a5fb214664 +Step 8/8 : CMD ["java", "-cp", "/devs-dclitest/bin:/devs-dclitest/lib/fwkdevs-v0.7", "Simulator"] + ---> Running in b287512ceb80 + ---> 530f80b5391d +Successfully built 530f80b5391d +Successfully tagged devs-dcli:test +``` +If successfully, right click on the main class, then *Run As* → *Java Application in Container*. + + +**Note:** In case Docker Tooling has some problems, install Docker on Ubuntu (follow guildlines [here](https://docs.docker.com/engine/install/ubuntu/)). Then build and run docker by command line: + +```bash +docker build -t devs-dcli:test . +``` + +```bash +docker run -it devs-dcli:test +``` + +### Initialize a project using a customized Devcontainer configuration + +On Terminal, type: + +```bash +dcli init +``` + +Insert image name of docker created: + +```bash +Image Name: devs-dcli:test +``` + +### Test running the DevContainer + +Type : + +```bash +dcli start +``` + +You will see the VSCode workspace opened. Test running the java program inside the DevContainer, type: + +```bash +java -cp /devs-dclitest/bin:/devs-dclitest/lib/fwkdevs-v0.7 Simulator +``` + + + +Stop the container: + +```bash +dcli stop +``` + +### Push DevContainer to the LIS Cluster + +#### 1. Export the DevContainer + +Type: + +```bash +dcli export +``` + +Once finished, you should see a squashfs file created. + +**Note:** Ignore the error on permission denied, or type: + +```bash +dcli export | chmod -R 777 tmp +``` + +#### 2. Push your Devcontainer on LIS Cluster + +On the first teminal window, connect to the cluster: + +```bash +ssh your-user.name@sms +``` + +Then create new folders: + +```bash +mkdir devcontainer_images # for the squashfs file +mkdir devs-dclitest # for your soucre code +``` + +On the second window, type: + +```bash +dcli config +``` + +```bash +Please provide the following information to create the .cluster_config file. +Cluster server name/address [sms]: sms +LIS cluster username []: your-user.name +Devcontainer workspace directory path [/workspace]: /workspace +Project directory (absolute path) to mount inside the devcontainer located on the cluster []: /home/your-user.name/devs-dclitest/ +Directory containing squashfs images (absolute path) located on the cluster []: /home/your-user.name/devcontainer_images/ + +.cluster_config file created successfully in the .devcontainer directory. +``` + +Now, push the squashfs file to the cluster +push your squashfs fil inside the cluster: + +```bash +dcli push +``` + +Then, push your source code to the cluster. E.g: + +```bash +scp -r -o ProxyJump="your-user.name@139.124.22.4" ./src/Car.java your-user.name@sms:/home/your-user.name/devs-dclitest/src/Car.java +``` + +### Run your DevContainer on LIS Cluster + +Type: + +```bash +dcli irun +``` + +Once connect successfully, type: + +```bash +java -cp /devs-dclitest/bin:/devs-dclitest/lib/fwkdevs-v0.7 Simulator +``` + +**Note:** To run manually, connect to the cluster first, then type: + +```bash +srun --container-image=/home/your-user.name/devcontainer_images//dcli_devs-dclitest.squashfs --container-mounts=/home/your-user.name/devs-dclitest/:/workspace --container-workdir=/workspace --cpus-per-task=12 --pty bash +``` \ No newline at end of file