OrigoShift is a solution for live streaming several 360-video camera streams with the ability for visitors to jump between cameras in a "google street view" fashion. This is paired with the ability for users to enter a 3D-environment as avatars and interact with each other. The system is implemented using web technologies. The client side consists of a website running in a browser.
Some of the key features:
[!NOTE] Prerequisites: Initially you will need Git to be able to fetch the repository. Git is installed by default on most linux systems. Additionally this project use the tool Ansible to install, update, setup and deploy the project on a server. To install ansible follow these instructions: https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html
To install Origoshift and run it on your own server, you first need to retrieve the repository from github. Using the terminal, go to your home folder on the server:
cd ~
Clone the repository from github and then go into the root directory of the project:
git clone https://github.com/immersed-web/origoshift.git --recurse-submodules
cd origoshift
This project relies on an .env file to configure relevant aspects of the system.
There is an example called example.env
in the root folder of the project. This is just an example file. You need to create an .env file (the filename should be .env, only), and in this file provide the relevant settings. One way would be to make a copy of the example file with the name .env and change the settings in the new file:
cp example.env .env
$
) anywhere in the .env file as that might fuck up everything ($
is used for variables in linux/bash/shells).\
) too.A normal setup would require setting values for:
The rest could be left as is.
You'll need the tool Ansible in order to follow this step. Follow the installation instructions for installing ansible here and come back when you have Ansible successfully installed on the server.
Now let's install and setup everything. cd into the ansible folder where all the playbook files are:
cd ansible
Setup all the system wide tools and dependencies
ansible-playbook setup_environment.yml
Log off and log back in. This is needed because the previous script (setup_environment.yml) added some environment variables to the user/profile (.bashrc or equivalent) that only gets loaded when the shell starts. Alternatively, you can manually "source" the shell config manually. e.g. source ~/.bashrc
, but it's probably more reliable to log off and on again.
Install the internal project dependencies and build the apps
ansible-playbook setup_project.yml
Go back to project root folder
cd ..
Run pm2 process manager in the project root (pm2 will pick up the file named ecosystem.config.js in the root, which specifies how to start and run the required processes)
pm2 start
pm2 delete all
cd ansible
ansible-playbook dangerous_sync_to_github_version.yml
ansible-playbook setup_environment.yml
(should usually not be needed, but in rare cases some edits are made to the environment/global dependencies)ansible-playbook setup_project.yml
cd ..
pm2 start
[!NOTE] Note: The file is named dangerous_sync_to_github_version.yml because it throws away any local additions/edits to the codebase (including not yet pushed commits). Thus it's only "dangerous" for a development environment and not a production server simply running the application.
The applications are run with a tool called pm2 that gets installed by the setup-environment.yml
ansible script. You can interact directly with pm2 using the command line. Here's a few examples:
To list the processes managed by pm2 and their status:
pm2 ls
To have a real-time look at what the applications are printing to the console while running, run:
pm2 logs
To do the same for only one running process, append the name. For example:
pm2 logs mediaserver
To get a terminal based overview dashboard, run:
pm2 monit
The following ports are required to be opened on the server:
Ports | Protocol | Description |
---|---|---|
22 | TCP | If you need to SSH in to the server (you will) |
80 | TCP | Serve standard http requests |
443 | TCP | Serve standard https requests |
40000-49999 | UDP | ports for the SFU mediaserver |
The project to develop and create this software was initiated by Lèv Grunberg. The development was a collaboration between the following organisations:
3D models created by:
This codebase (excluding external dependencies, such as libraries and/or software frameworks) is written by me, Gunnar Oledal. The project is licensed under MIT. The license text can be found in the file LICENSE in the project root. External dependencies, such as libraries and/or software frameworks in this repository, holds up to their own respective licenses.