|
|
@ -1,58 +1,87 @@ |
|
|
|
# Contributing |
|
|
|
|
|
|
|
## Building Microstack |
|
|
|
## Building MicroStack |
|
|
|
|
|
|
|
Currently, you must build microstack on a machine running Ubuntu 16.04 Xenial. A goal of the project is to expand this to other environments, but for now, there are some Debian packages specific to Xenial required in snapcraft.yaml. |
|
|
|
MicroStack builds are tested on an Ubuntu 18.04 LTS machine with 16G |
|
|
|
of RAM, two cpu cores, and 50G of free disk space. You should be able |
|
|
|
to build MicroStack on any machine matching those minimum specs, as |
|
|
|
long as it is capable of running bash and snapd. If you run into any |
|
|
|
snags doing so, please file bugs at |
|
|
|
https://bugs.launchpad.net/microstack |
|
|
|
|
|
|
|
To build microstack, do the following: |
|
|
|
To build MicroStack on a capable machine, run: |
|
|
|
|
|
|
|
``` |
|
|
|
export PATH=/snap/bin:$PATH |
|
|
|
sudo snap install --classic snapcraft |
|
|
|
git clone git@github.com:CanonicalLtd/microstack.git |
|
|
|
cd microstack |
|
|
|
snapcraft |
|
|
|
``` |
|
|
|
git clone https://opendev.org/x/microstack.git |
|
|
|
cd microstack |
|
|
|
tox |
|
|
|
|
|
|
|
Optionally, if you want to keep the system clean of dependencies, you can install lxd and do a cleanbuild (note that the apt packaged version of lxd in Xenial won't work -- you want to use the snap). |
|
|
|
This will run tools/multipass_build.sh, which installs some |
|
|
|
dependencies on your system, and then run some tests. If you want to |
|
|
|
have more control over the build process and installed dependencies, |
|
|
|
replace the tox line with: |
|
|
|
|
|
|
|
``` |
|
|
|
sudo snap install --classic lxd |
|
|
|
sudo usermod -aG lxd <your username> |
|
|
|
newgrp lxd |
|
|
|
lxd init # Going with the defaults is fine |
|
|
|
``` |
|
|
|
snapcraft |
|
|
|
|
|
|
|
Then replace `snapcraft` above with `snapcraft cleanbuild` |
|
|
|
or |
|
|
|
|
|
|
|
## How the Code is Structured |
|
|
|
snapcraft --use-lxd |
|
|
|
|
|
|
|
Microstack is a Snap, which means that, after it has been built, it contains all the code and dependencies that it needs, destined to be mounted in a read only file system on a host. |
|
|
|
(You may have to install snapcraft and lxd or multipass on your system |
|
|
|
first if you go this route -- inspect tools/multipass_build.sh and |
|
|
|
tools/lxd_build.sh for tips.) |
|
|
|
|
|
|
|
Before contributing, you probably want to read the general Snap Documentation here: https://docs.snapcraft.io/snap-documentation/3781 |
|
|
|
## How the code is structured |
|
|
|
|
|
|
|
There are several important files and directories in microstack, some of which are like those in other snaps, some of which are unique to microstack: |
|
|
|
MicroStack is a Snap, which means that, after it has been built, it |
|
|
|
contains all the code and dependencies that it needs, destined to be |
|
|
|
mounted in a read only file system on a host. |
|
|
|
|
|
|
|
### `./snapcraft.yaml` |
|
|
|
Before contributing, you probably want to read the general Snap |
|
|
|
Documentation here: https://docs.snapcraft.io/snap-documentation/3781 |
|
|
|
|
|
|
|
This is the core of the snap. You'll want to start here when it comes to adding code. And you may not need to leave this file at all. |
|
|
|
There are several important files and directories in MicroStack, some |
|
|
|
of which are like those in other snaps, some of which are unique to |
|
|
|
MicroStack: |
|
|
|
|
|
|
|
### `./snap-overlay` |
|
|
|
### The Snapcraft yaml |
|
|
|
|
|
|
|
Any files you add to snap-overlay will get written to the corresponding place in the file hierarchy under `/snap/microstack/common/`. Drop files in here if you want to insert a file or directory that does not come bundled by default with the Openstack source tarballs. |
|
|
|
./snapcraft.yaml |
|
|
|
|
|
|
|
### `./snap-overlay/snap-openstack.yaml` |
|
|
|
This is the core of the snap. You'll want to start here when it comes |
|
|
|
to adding code. And you may not need to leave this file at all. |
|
|
|
|
|
|
|
This is a yaml file unique to Snaps created by the Openstack team at Canonical. It creates a command called `snap-openstack`, which wraps Openstack daemons and scripts. |
|
|
|
### Snap overlay |
|
|
|
|
|
|
|
Documentation for this helper lives here: https://github.com/openstack/snap.openstack |
|
|
|
./snap-overlay |
|
|
|
|
|
|
|
Any files you add to snap-overlay will get written to the |
|
|
|
corresponding place in the file hierarchy under |
|
|
|
`/snap/microstack/common/`. Drop files in here if you want to insert a |
|
|
|
file or directory that does not come bundled by default with the |
|
|
|
OpenStack source tarballs. |
|
|
|
|
|
|
|
### Snap-openstack yaml |
|
|
|
|
|
|
|
./snap-overlay/snap-openstack.yaml |
|
|
|
|
|
|
|
This is a yaml file unique to Snaps created by the OpenStack team at |
|
|
|
Canonical. It creates a command called `snap-openstack`, which wraps |
|
|
|
OpenStack daemons and scripts. |
|
|
|
|
|
|
|
Documentation for this helper lives here: |
|
|
|
https://github.com/openstack/snap.openstack |
|
|
|
|
|
|
|
It's installed by the openstack-projects part. |
|
|
|
|
|
|
|
If you're adding an Openstack component to the snap, you may find it useful to take a look at the parts and apps that take advantage of snap-openstack, and add your own section to `snap-openstack.yaml`. |
|
|
|
If you're adding an OpenStack component to the snap, you may find it |
|
|
|
useful to take a look at the parts and apps that take advantage of |
|
|
|
snap-openstack, and add your own section to `snap-openstack.yaml`. |
|
|
|
|
|
|
|
### Filing Bug and Submitting Pull Requests |
|
|
|
### Filing bugs and submitting pull requests |
|
|
|
|
|
|
|
We track bugs and features on launchpad, at https://bugs.launchpad.net/microstack |
|
|
|
We track bugs and features on Launchpad, at |
|
|
|
https://bugs.launchpad.net/microstack |
|
|
|
|
|
|
|
To submit a bugfix or feature, please fork the github repo, and create a pull request against it. The microstackers team will see it and review your code. |
|
|
|
To submit a bugfix or feature, please create a Merge Proposal against |
|
|
|
the OpenDev repository. See the OpenStack Developer's Guide for more |
|
|
|
detail: https://docs.openstack.org/infra/manual/developers.html |