Skip to content

update contributing doc #452

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cooktheryan merged 3 commits into from
Nov 30, 2021
Merged

update contributing doc #452

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
839c686
update contributing doc
osilkin98 Nov 10, 2021
1499727
touchup on proposal section
osilkin98 Nov 11, 2021
fa32ffe
reword contributing doc
osilkin98 Nov 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
190 changes: 15 additions & 175 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,188 +1,28 @@
# 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.
Welcome to MicroShift! We are glad you are interested in this project.
If you’d like to jump right in with MicroShift then check out the [open issues](https://github.com/redhat-et/microshift/issues), pull requests are always welcome.

This guide will primarily focus on running MicroShift within a VM using Vagrant.
## Documentation

Looking for the docs? Well, look no further; [microshift.io](https://microshift.io) has the answers.
If you would like to contribute to the documentation pages, check out the [documentation repo](https://github.com/redhat-et/microshift-documentation).

## (optional) Developing with Vagrant

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

You can find a guide on how to install it for your system [here](https://www.vagrantup.com/downloads).
Notice a bug? File an issue [here](https://github.com/redhat-et/microshift/issues/new/choose) and provide as much information as possible.

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](https://app.vagrantup.com/fedora/boxes/34-cloud-base), however you can substitute any vagrant image of your choice.
## Enhancement Proposals

MicroShift’s goal is to create a minimal core that can functionally operate as close to OpenShift as
possible while maintaining a low resource impact. We are always looking for enhancement proposals,
so feel free to create an enhancement issue with a link to a document that explains your proposal.
The enhancement will be considered as long as it aligns with [MicroShift's design goals](https://github.com/redhat-et/microshift/blob/main/docs/design/design.md).

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

Join us on [Slack](https://microshift.slack.com)! ([Invite to the Slack space](https://join.slack.com/t/microshift/shared_invite/zt-uxncbjbl-XOjueb1ShNP7xfByDxNaaA))


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

```sh
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:

```rb
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`:

```rb
# 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](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)



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](./docs/pics/vscode-remote-button.png)

Select the option to open an SSH configuration file:
![Dropdown Menu](./docs/pics/remote-ssh-dropdown.png)

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
](https://medium.com/@lopezgand/connect-visual-studio-code-with-vagrant-in-your-local-machine-24903fb4a9de))*


## Running MicroShift Locally

### Pre-Installation

You will need to install the required binaries:
- git
- make
- golang
- glibc
- podman

```sh
# 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](https://podman.io/getting-started/installation)


Next you'll want to clone the repository and cd into it:
```sh
git clone https://github.com/redhat-et/microshift.git
cd microshift
```

### Building MicroShift

Now we can build MicroShift:

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

Community meetings are held weekly, Wednesdays at 10:30AM - 11:00AM EST. Be sure to join the community [calendar](https://calendar.google.com/calendar/embed?src=nj6l882mfe4d2g9nr1h7avgrcs%40group.calendar.google.com&ctz=America%2FChicago)! Click "Google Calendar" in the lower right-hand corner to subscribe.