Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@fresearchgroup
fresearchgroup authored Dec 28, 2023
1 parent 0c18d51 commit 2d8a2e8
Showing 1 changed file with 64 additions and 65 deletions.
129 changes: 64 additions & 65 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,43 +34,72 @@ This system allows the users to drag and drop Arduino components from the left p

![Arduino Demo](demo/demo-arduino.gif)

## Documentation

The latest version of documentation for the project is maintained on [esim-cloud.readthedocs.io](https://esim-cloud.readthedocs.io/)

## Installation

### Basic Setup
* [Docker](https://docs.docker.com/get-docker/) and [docker-compose](https://docs.docker.com/compose/install/) will be required for production and development environments.
* Make sure that you install both of them specific to your OS and version (Linux, Windows, Mac)
* ```git clone https://github.com/frg-fossee/eSim-Cloud.git```
* ```cd eSim-Cloud```
* This is only a one time process
* Ubuntu (Requirements)
* Install [Docker](https://docs.docker.com/desktop/install/ubuntu/)
* Install docker compose: ```sudo apt get install docker-compose```
* Windows (Requirements)
* Install WSL (Windows Subsystem for Linux)
* Open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting "Run as administrator"
* ```wsl --install```
* Restart your machine.
* Install [Docker](https://docs.docker.com/desktop/install/windows-install/)
* Start the docker desktop application
* Mac (Requirements)
* Install [Docker](https://docs.docker.com/desktop/install/mac-install/)
* Start the docker desktop application
* Setting up
* Fork this repository. Make sure that you fork all the branches.
* Windows users: Use the Ubuntu App to start the terminal and then proceed ahead. Do not user PowerShell.
* Clone your forked repo on your machine: ```git clone https://github.com/<yourGitHubUserName>/eSim-Cloud.git```
* ```cd eSim-Cloud```
* ```git checkout develop```: This will switch to the develop branch
* ```/bin/bash first_run.dev.sh```: This will set up and install all the necessary packages and docker images. Depending on your connection it would take around 40 to 45 minutes

## Starting the system
* Before proceeding ahead, start your Docker Desktop application (Windows and Mac users only)
* Open (terminal - Ubuntu/Mac users) (WSL ubuntu app - Windows users)

### Development Environment (for coders/developers)
* ```docker-compose -f docker-compose.dev.yml --env-file .env up ```
* eSim: Browse http://localhost/ and click the Launch button under eSim
* Login credentials
* Username: admin
* Password: admin
* Arduino: Browse http://localhost:4200/

### Production Environment
* Setup env (Change default credentials)
* ``` cp .env .env.prod ```
* Run docker (in background)
* ``` docker-compose -f docker-compose.prod.yml --env-file .env.prod up --scale django=2 --scale celery=3 -d```
* Note: ```-d``` option will run the process in the background.
* Remove ```-d``` to view all logs and process in the terminal.
* Migrations and seed eSim SVGs (after DB and django has finished initializing)
* ```docker ps``` # Find docker id of django. It would be something like 'c4ac75dd1937'
* ```docker exec -it ContainerID /bin/bash```
* ```cp .env .env.prod ```: Only for the first time
* ```docker-compose -f docker-compose.prod.yml --env-file .env.prod up```
* Browse http://localhost/ and click the launch button for eSim and Arduino, respectively
* Login credentials
* Username: admin
* Password: admin

### Applying Migrations (Only if needed)
* At times, while setting up the system, the database might not get set up as required. In such a case, when you visit the gallery of eSim or Arduino, you will not find the sample circuits. Moreover, in eSim, the components in the left pane will not be loaded. In such a case, do the following
* Make sure that the dockers are running i.e. you have started either the development or production environment
* Open up a new terminal.
* ```docker ps``` This command displays the container ids of all running docker containers.
* Look for Django's container ID. It would be something like 'c4ac75dd1937'
* ```docker exec -it <ContainerID> /bin/bash```
* ```sh migrations.sh```

### Development Environment
[![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.svg)](https://ssh.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Ffrg-fossee%2FeSim-Cloud&cloudshell_git_branch=develop&cloudshell_print=first_run.dev.sh&cloudshell_tutorial=README.md)

* Build and run migrations (First time only)
* Pulls the latest dev image from GitHub
* ``` /bin/bash first_run.dev.sh ```
* Run docker
* ``` docker-compose -f docker-compose.dev.yml --env-file .env up ```
* It might take a while to initialize / throw some errors if they're initialized in the wrong order.
* Running the command again will most likely fix the issue.

### Other useful commands
* These containers are only for dev environment. In production, the compiled files will be served by nginx
## Other Commands
* To view Django admin panel
* Browse http://localhost/api/admin and login with the following credentials
* Username: admin
* Password: admin
* If port 80 is already being used on your system, due which nginx is unable to start for this system and throws an error, you can kill the existing process that uses port 80
* ```sudo kill -9 $(sudo lsof -t -i:80)```
* To start dockers on the server
* ``` docker-compose -f docker-compose.prod.yml --env-file .env.prod up --scale django=2 --scale celery=3 -d```
* Note: -d option runs the dockers in the background. To view the logs in the terminal, remove this option
* Scale django and celerey as required. Remove them, if the server is unable to take the load
* Restart nginx
* Development environment: ``` docker-compose -f docker-compose.dev.yml --env-file .env restart nginx```
* Production environment: ``` docker-compose -f docker-compose.prod.yml --env-file .env.prod restart nginx```
* Manually build containers
* ```docker-compose -f docker-compose.dev.yml --env-file .env build```
* Run backend container only
Expand All @@ -79,39 +108,9 @@ The latest version of documentation for the project is maintained on [esim-cloud
* ``` docker-compose -f docker-compose.dev.yml --env-file .env up eda-frontend ```
* Run Arduino along with backend
* ``` docker-compose -f docker-compose.dev.yml --env-file .env up arduino-frontend ```
* Restart nginx
* Dev env: ``` docker-compose -f docker-compose.dev.yml --env-file .env restart nginx```
* Prod env: ``` docker-compose -f docker-compose.prod.yml --env-file .env.prod restart nginx```

### Pulling docker images
* Docker images can be directly pulled from GitHub instead of building on system
```console
$ echo $GITHUB_TOKEN | docker login docker.pkg.github.com --username [github_username] --password-stdin
$ docker-compose -f docker-compose.dev.yml pull
$ docker-compose -f docker-compose.dev.yml up --env-file .env -d db
----WAIT FOR DB TO FINISH INITIALIZING-----
$ docker-compose -f docker-compose.dev.yml --env-file .env up
```

### Ubuntu Installation Dump
* These are all commands being executed to setup the project's development environment on a fresh ubuntu system with username ```ubuntu```
* If you notice ``` ERROR: UnixHTTPConnectionPool(host='localhost', port=None): Read timed out. ``` or ``` Exited with code 137```, it means that docker / host system ran out of memory

```console
$ git clone https://github.com/frg-fossee/eSim-Cloud/
$ cd eSim-Cloud/
$ git checkout develop
$ sudo curl -L "https://github.com/docker/compose/releases/download/1.25.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
$ sudo chmod +x /usr/local/bin/docker-compose
$ sudo apt-get remove docker docker-engine docker.io containerd runc
$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh get-docker.sh
$ sudo usermod -aG docker ubuntu
$ sudo systemctl start docker
$ sudo systemctl status docker
$ sudo docker ps
$ sudo ./first_run.dev.sh
```

## Documentation
The latest version of documentation for the project is maintained on [esim-cloud.readthedocs.io](https://esim-cloud.readthedocs.io/)

## Tech stack
* Simulation backend
Expand Down

0 comments on commit 2d8a2e8

Please sign in to comment.