Skip to content

Latest commit

 

History

History
188 lines (129 loc) · 4.97 KB

CONTRIBUTING.md

File metadata and controls

188 lines (129 loc) · 4.97 KB
Raw

Contributing to Microshift

If you would like to develop Microshift locally, you can follow this guide on getting it installed and running through the provided Makefile.

This guide will primarily focus on running Microshift within a VM using Vagrant.

(optional) Developing with Vagrant

To get started with development, it is recommended to use Vagrant for VM provisioning, however it is not necessary.

You can find a guide on how to install it for your system here.

Once Vagrant is installed, you will need to create a Vagrant box for the operating system of your choice. For this example we will be looking at a fedora 34 cloud image, however you can substitute any vagrant image of your choice.

First, navigate to the Microshift directory on your host system, or another designated directory where we will be storing the Vagrantfile.

Next, download the vagrant image. For this example we will use a fedora 34 cloud image:

vagrant box add fedora/34-cloud-base

Depending on the image, Vagrant will ask you to select a Virtualization provider, just select the first one.

Once that downloads, initialize the repository for launching your image:

vagrant init fedora/34-cloud-base

Running this command will create a Vagrantfile in your working directory which is used to configure your vagrant box.

Before we start our Vagrant box, we will need to increase the amount of RAM available to the system. To do this, edit the Vagrantfile and configure your provider settings to include the following:

    config.vm.provider "libvirt" do |v|
        # provides 3GB of memory
        v.memory = 3072
        # for parallelization
        v.cpus = 2
    end

The value of config.vm.provider depends on the provider you selected when you ran vagrant add earlier. For example, if you selected virtualbox then the first line should be: config.vm.provider "virtualbox" do |v|

Now we can start the VM:

vagrant up

Once the VM is up, connect to it:

vagrant ssh

(Extra Optional) Connecting VSCode to Vagrant

If you're using VSCode, you can connect to your vagrant box with a few extra steps.

Increasing Memory Requirements

Since VS Code leans more on the heavy side of development, the RAM usage on your Vagrant environment can go up to 5GB, and therefore we will need to modify the Vagrantfile to increase the amount of available RAM from 3GB to 5GB (or 6GB if you want to be safe). To do this, set v.memory to the following in your Vagrantfile:

        # provides 5GB of memory
        v.memory = 5120
        # provides 6GB of memory
        v.memory = 6144

Setting up an SSH Profile

First we need to ask Vagrant for an SSH config file. From your host machine, run:

vagrant ssh-config > ssh-config.conf

You can edit the ssh-config.conf file to change the hostname from default to vagrant to be more easily identifiable, but that's up to you. :)

Here's an example of my working SSH config file:

Host default
  HostName 127.0.0.1
  User vagrant
  Port 2222
  UserKnownHostsFile /dev/null
  StrictHostKeyChecking no
  PasswordAuthentication no
  IdentityFile /path/to/microshift/.vagrant/machines/default/virtualbox/private_key
  IdentitiesOnly yes
  LogLevel FATAL

Next, you'll want to install the Remote - SSH extension from the VSCode Marketplace

With the extension installed, you'll click on the green bottom in the bottom-left corner of VSCode to open a dropdown menu for SSH options:

VSCode Remote Button

Select the option to open an SSH configuration file: Dropdown Menu

Next you'll want to navigate to the "Remote Explorer" tab on the left-hand side of VSCode, then select on the vagrant target (default if you haven't renamed it) and click on the button to connect to it in a remote window.

(Credits to Andrés Lopez for this guide: Connect Visual Studio Code with Vagrant in your local machine )

Running Microshift Locally

Pre-Installation

You will need to install the required binaries:

  • git
  • make
  • golang
  • glibc
  • podman
# Fedora/CentOS 
sudo dnf install \
    git \
    make \
    golang \    
    glibc-static

# Ubuntu
sudo apt install \
    git \
    build-essential \   # provides Make
    golang-go \
    glibc

To install podman, you can find the appropriate guide for your respective system: Install Podman

Next you'll want to clone the repository and cd into it:

git clone https://github.com/redhat-et/microshift.git
cd microshift

Building Microshift

Now we can build Microshift:

make build
CONFIG_ENV_ONLY=true ./install.sh
sudo ./microshift run