Skip to content

Commit

Permalink
chore(docs) add roadmap and extend readme with changelog. rename hack…
Browse files Browse the repository at this point in the history 
…ing to contributions guidelines WD-11364

Signed-off-by: David Edler <[email protected]>
  • Loading branch information
@edlerd
edlerd committed Jun 18, 2024
1 parent fc277d7 commit 4e6a3be
Show file tree
Hide file tree
Showing 5 changed files with 216 additions and 141 deletions.
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Fixes [list issues/bugs if needed]

1. Run the LXD-UI:
- On the demo server via the link posted by @webteam-app below. This is only available for PRs created by collaborators of the repo. Ask @mas-who or @edlerd for access.
- With a local copy of this branch, run as described [here](../HACKING.md#setting-up-for-development).
- With a local copy of this branch, [build and run as described in the docs](../CONTRIBUTING.md#setting-up-for-development).
2. Perform the following QA steps:
- [List the steps to QA the new feature(s) or prove that a bug has been resolved]

Expand Down
167 changes: 167 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
# Sending a pull request

1. Fork the repository

2. Clone the fork to your local machine and add the upstream remote:

git clone https://github.com/<your username>/lxd-ui.git
cd lxd-ui
git remote add upstream https://github.com/canonical/lxd-ui.git

3. Setup LXD as a backend:

<details>
<summary>Setup LXD - Linux (with snap)</summary>
<br/>
<pre><code>snap install lxd
lxd init # can accept all defaults
lxc config set core.https_address "[::]:8443"
lxc config set user.show_permissions=true</code></pre>
</details>

<details>
<summary>Setup LXD - Mac</summary>
<br/>

> :warning: **VM instances cannot be created with LXC + Multipass on a Mac**. Nested virtualization is unsupported.
First, if you have not already, you need to install [Homebrew](https://brew.sh/).

Then install LXC client with brew:

<pre><code>brew install lxc</code></pre>

LXD cannot run natively on a Mac, so you need to connect LXC to a remote LXD server. You can set up one inside a Multipass instance. [How to install Multipass on macOS - Using brew](https://multipass.run/docs/installing-on-macos#heading--use-brew)

Once you have LXC and Multipass installed, we can create a Multipass instance where we will run the LXD daemon:

<pre><code># launch a new instance called "lxd" with 2 CPUs, 4G memory, and 50G of disk space - gauge these values as you prefer
multipass launch -n lxd -c 2 -m 4G -d 50G</code></pre>

If you get the `Launched: lxd` output, it means that the command succeeded. We can now launch a shell into the newly created instance:

<pre><code>multipass shell lxd</code></pre>

You should be greeted with the Ubuntu shell login message `Welcome to Ubuntu ...`. Make sure the latest version of LXD is installed:

<pre><code>sudo snap refresh lxd --channel=latest/stable</code></pre>

This command will either output `snap "lxd" has no updates available` or update lxd to the latest stable version.

Initialise LXD - replace `your-password` with a password of your choice - and then close the multipass shell:

<pre><code>sudo lxd init --auto --trust-password your-password --network-address '[::]'
exit</code></pre>

Connect the LXD server in Multipass to the local LXC. In a terminal on your Mac, run:

<pre><code>lxc remote add default $(multipass info lxd | grep IPv4 | awk '{print $2}') --password your-password --accept-certificate</code></pre>

(replace `your-password` with the password you selected before)

You should get a message saying: `Client certificate now trusted by server: default`

Switch the remote to the `default` server that we have just added:

<pre><code>lxc remote switch default</code></pre>

Launch an instance with the lxc command on your Mac:

<pre><code>lxc launch ubuntu:jammy test-jammy</code></pre>

If this succeeds, the setup of LXC and LXD is complete. Finally, expose the API on port 8443:

<pre><code>lxc config set core.https_address "[::]:8443"</code></pre>
</details>


4. Install [dotrun](https://github.com/canonical/dotrun#installation) and launch it from the head of this repo

dotrun

You should enable a firewall as `dotrun` exposes an api to start or interact with unprivileged containers on your public
ip via port `8407`. Ensure that the lxd API on port `8443` is open, so `dotrun` can access it.

The first time, running `dotrun` will generate certificates for you. You can find them in the `keys` folder on the top level of
the repo. Trust them from your local `lxc` with

sudo lxc config trust add keys/lxd-ui.crt

If you are on a Mac and running LXD inside Multipass, set the `LXD_UI_BACKEND_IP` in the `.env.local` file:

echo "LXD_UI_BACKEND_IP=$(multipass info lxd | grep IPv4 | awk '{print $2}')" > .env.local

Now you can open https://localhost:8407/ to reach lxd-ui.


5. To enable pre-commit checks, after the first successful run of `dotrun`, execute `yarn hooks-add`. To remove them, run `yarn hooks-remove`.


6. Create a new topic branch:

git checkout -b my-topic-branch


7. Make changes, commit, and push to your fork:

git push -u origin HEAD


8. Go to the [repository](https://github.com/canonical/lxd-ui/) and open a pull request.

The team actively monitors for new pull requests. We will review your PR and either merge it, request changes to it, or close it with an explanation.

# License and copyright
All contributors must sign the [Canonical contributor license agreement](https://ubuntu.com/legal/contributors), which gives Canonical permission to use the contributions. The author of a change remains the copyright holder of their code (no copyright assignment).

# Signing off commits
All commits are required to be signed off using a GPG key. You can use the following references to set up your git configurations for commit signing.
1. [Generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) or [use an existing GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/checking-for-existing-gpg-keys). Make sure that the GPG key is associated to the email that you are using within your git configuration. If you have multiple GPG keys set up, you should [tell git about your signing GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key).
2. [Add a GPG key to your Github account](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account). This will make your commits verified on Github.
3. To sign commits, you should enter the git command with additional flags as shown in this example: `git commit -s -S -a -m "initial commit"`.
4. To make your life a little easier, you can setup a git alias for signing commits with `git config alias.sc 'commit -s -S -a'`. Now you can sign your commits with `git sc -m "initial commit"` for example. Note this only enables the alias for your local git configuration.

# Supporting multiple lxd versions
When making a contribution to this project, please take note that the UI should degrade gracefully for all lxd LTS versions later than v5.0. To acheive this, there are two processes that should be followed:

1. When adding a new feature that introduces lxd api endpoints that are not currently used in the project, make sure you check against `api_extensions` returned by the `GET /1.0/` endpoint if the new endpoints used exists for older lxd versions. If the new endpoints are not supported in an older lxd version, then you should either hide or disable a portion of the new feature for the relevant lxd version. A useful `useSupportedFeatures` hook can be used for this purpose. You can also find a comprehensive list of `api_extensions` refrences in the [lxd documentation](https://documentation.ubuntu.com/lxd/en/latest/api-extensions/).
2. You should write e2e tests that covers the new feature for all supported lxd versions. For example, if your feature is hidden for an older lxd server version, you should test that it is not displayed in the browser for that lxd version.

# End-to-end tests

Install playwright and its browsers

npx playwright install

The e2e tests can be run against LXD 5.0, or the edge version of LXD. If you want to run the tests against the edge version, first make sure your lxd is up to date with

snap refresh lxd --channel latest/edge

The tests expect the environment on localhost to be accessible. Execute `dotrun` first then run the tests against the latest LXD version with

yarn test-e2e-edge

or against the LTS LXD versions with

yarn test-e2e-5.21-edge
yarn test-e2e-5.0-edge

### Nice utilities from Playwright

Generate new tests with helper [Doc](https://playwright.dev/docs/codegen)

npx playwright codegen --ignore-https-errors https://localhost:8407/

Explore and debug tests in UI mode [Doc](https://playwright.dev/docs/test-ui-mode)

npx playwright test --ui

Learn more about the [test architecture](ARCHITECTURE.MD#e2e-test-setup-for-multiple-lxd-versions) in our architecture documentation.

# Advanced setup

Learn how to
- [Setup local LXD cluster](https://github.com/canonical/lxd-ui/wiki/Setup-local-LXD-cluster) inside LXD to enable clustering features
- [Setup oidc login](https://github.com/canonical/lxd-ui/wiki/Setup-oidc-login) to enable SSO authentication
- See [Architecture](ARCHITECTURE.MD) for details on the dev setup.

139 changes: 1 addition & 138 deletions HACKING.md
View file
Original file line number Diff line number Diff line change
@@ -1,138 +1 @@
# Setting up for development

<details>
<summary>Setup LXD - Linux (with snap)</summary>
<br/>
<pre><code>snap install lxd
lxd init # can accept all defaults
lxc config set core.https_address "[::]:8443"
lxc config set user.show_permissions=true</code></pre>
</details>

<details>
<summary>Setup LXD - Mac</summary>
<br/>

> :warning: **VM instances cannot be created with LXC + Multipass on a Mac**. Nested virtualization is unsupported.
First, if you have not already, you need to install [Homebrew](https://brew.sh/).

Then install LXC client with brew:

<pre><code>brew install lxc</code></pre>

LXD cannot run natively on a Mac, so you need to connect LXC to a remote LXD server. You can set up one inside a Multipass instance. [How to install Multipass on macOS - Using brew](https://multipass.run/docs/installing-on-macos#heading--use-brew)

Once you have LXC and Multipass installed, we can create a Multipass instance where we will run the LXD daemon:

<pre><code># launch a new instance called "lxd" with 2 CPUs, 4G memory, and 50G of disk space - gauge these values as you prefer
multipass launch -n lxd -c 2 -m 4G -d 50G</code></pre>

If you get the `Launched: lxd` output, it means that the command succeeded. We can now launch a shell into the newly created instance:

<pre><code>multipass shell lxd</code></pre>

You should be greeted with the Ubuntu shell login message `Welcome to Ubuntu ...`. Make sure the latest version of LXD is installed:

<pre><code>sudo snap refresh lxd --channel=latest/stable</code></pre>

This command will either output `snap "lxd" has no updates available` or update lxd to the latest stable version.

Initialise LXD - replace `your-password` with a password of your choice - and then close the multipass shell:

<pre><code>sudo lxd init --auto --trust-password your-password --network-address '[::]'
exit</code></pre>

Connect the LXD server in Multipass to the local LXC. In a terminal on your Mac, run:

<pre><code>lxc remote add default $(multipass info lxd | grep IPv4 | awk '{print $2}') --password your-password --accept-certificate</code></pre>

(replace `your-password` with the password you selected before)

You should get a message saying: `Client certificate now trusted by server: default`

Switch the remote to the `default` server that we have just added:

<pre><code>lxc remote switch default</code></pre>

Launch an instance with the lxc command on your Mac:

<pre><code>lxc launch ubuntu:jammy test-jammy</code></pre>

If this succeeds, the setup of LXC and LXD is complete. Finally, expose the API on port 8443:

<pre><code>lxc config set core.https_address "[::]:8443"</code></pre>
</details>

Install dotrun as described in https://github.com/canonical/dotrun#installation Launch it from the head of this repo

dotrun

You should enable a firewall as `dotrun` exposes an api to start or interact with unprivileged containers on your public
ip via port `8407`. Ensure that the lxd API on port `8443` is open, so `dotrun` can access it.

The first time, running `dotrun` will generate certificates for you. You can find them in the `keys` folder on the top level of
the repo. Trust them from your local `lxc` with

sudo lxc config trust add keys/lxd-ui.crt

If you are on a Mac and running LXD inside Multipass, set the `LXD_UI_BACKEND_IP` in the `.env.local` file:

echo "LXD_UI_BACKEND_IP=$(multipass info lxd | grep IPv4 | awk '{print $2}')" > .env.local

Now you can open https://localhost:8407/ to reach lxd-ui.

To enable pre-commit checks, after the first successful run of `dotrun`, execute `yarn hooks-add`. To remove them, run `yarn hooks-remove`.

# License and copyright
All contributors must sign the [Canonical contributor license agreement](https://ubuntu.com/legal/contributors), which gives Canonical permission to use the contributions. The author of a change remains the copyright holder of their code (no copyright assignment).

# Signing off commits
All commits are required to be signed off using a GPG key. You can use the following references to set up your git configurations for commit signing.
1. [Generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) or [use an existing GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/checking-for-existing-gpg-keys). Make sure that the GPG key is associated to the email that you are using within your git configuration. If you have multiple GPG keys set up, you should [tell git about your signing GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key).
2. [Add a GPG key to your Github account](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account). This will make your commits verified on Github.
3. To sign commits, you should enter the git command with additional flags as shown in this example: `git commit -s -S -a -m "initial commit"`.
4. To make your life a little easier, you can setup a git alias for signing commits with `git config alias.sc 'commit -s -S -a'`. Now you can sign your commits with `git sc -m "initial commit"` for example. Note this only enables the alias for your local git configuration.

# Supporting multiple lxd versions
When making a contribution to this project, please take note that the UI should degrade gracefully for all lxd LTS versions later than v5.0. To acheive this, there are two processes that should be followed:

1. When adding a new feature that introduces lxd api endpoints that are not currently used in the project, make sure you check against `api_extensions` returned by the `GET /1.0/` endpoint if the new endpoints used exists for older lxd versions. If the new endpoints are not supported in an older lxd version, then you should either hide or disable a portion of the new feature for the relevant lxd version. A useful `useSupportedFeatures` hook can be used for this purpose. You can also find a comprehensive list of `api_extensions` refrences in the [lxd documentation](https://documentation.ubuntu.com/lxd/en/latest/api-extensions/).
2. You should write e2e tests that covers the new feature for all supported lxd versions. For example, if your feature is hidden for an older lxd server version, you should test that it is not displayed in the browser for that lxd version.

# End-to-end tests

Install playwright and its browsers

npx playwright install

The e2e tests can be run against LXD 5.0, or the edge version of LXD. If you want to run the tests against the edge version, first make sure your lxd is up to date with

snap refresh lxd --channel latest/edge

The tests expect the environment on localhost to be accessible. Execute `dotrun` first then run the tests against the latest LXD version with

yarn test-e2e-edge

or against the LTS LXD versions with

yarn test-e2e-5.21-edge
yarn test-e2e-5.0-edge

### Nice utilities from Playwright

Generate new tests with helper [Doc](https://playwright.dev/docs/codegen)

npx playwright codegen --ignore-https-errors https://localhost:8407/

Explore and debug tests in UI mode [Doc](https://playwright.dev/docs/test-ui-mode)

npx playwright test --ui

# Advanced setup

Learn how to
- [Setup local LXD cluster](https://github.com/canonical/lxd-ui/wiki/Setup-local-LXD-cluster) inside LXD to enable clustering features
- [Setup oidc login](https://github.com/canonical/lxd-ui/wiki/Setup-oidc-login) to enable SSO authentication
- See [Architecture](ARCHITECTURE.MD) for details on the dev setup.

moved to [contribution guidelines](CONTRIBUTING.md)
11 changes: 9 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,19 @@ Targets small and large scale private clouds.

You might want to:

- Read the [contributing guide](CONTRIBUTING.md), to learn about our development process and how to build and test your changes.
- [View the source](https://github.com/canonical/lxd-ui) on GitHub.
- Read about [running the UI from git checkout](HACKING.md), tests and advanced setup.

# Architecture

LXD-UI is a single page application written in TypeScript and React. See [Architecture](ARCHITECTURE.MD) for details on bundling with [LXD](https://github.com/canonical/lxd) and the dev setup.
LXD-UI is a single page application written in TypeScript and React. See [Architecture](ARCHITECTURE.MD) for details on bundling with [LXD](https://github.com/canonical/lxd) and the dev setup.

# Changelog

The [changelog](https://github.com/canonical/lxd-ui/releases) is regularly updated to reflect what's changed in each new release.

# Roadmap
Future plans and high-priority features and enhancements can be found in the [roadmap](ROADMAP.md).

# Examples

Expand Down
38 changes: 38 additions & 0 deletions ROADMAP.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Roadmap for 24.10 from April 2024 until October 2024

- Create instances from a snapshot or instance
- Add devices (GPU, proxies and others)
- Virtual machine import (from qcow2 and VMDK)
- Storage driver support: pure
- Systemwide icons/semiotics
- Error message knowledge base
- Gracefully adjust to users with lower permissions
- Move or copy storage volumes
- PWA Support
- Secure dev lifecycle

# Roadmap for 24.04 from October 2023 until April 2024

- Ceph management
- Integration with the configuration API
- Messaging and Notifications
- authorisation management
- CRUD volume snapshots

# Roadmap for 23.10 from April 2023 until October 2023

- Cluster
- Authentication & Authorization
- storage volumes and ISO imports
- networks OVN and bridged
- Advanced networking (stretch)
- Advanced storage (stretch)

# Roadmap for 23.04 from October 2022 until April 2023

- VGA support with spice html5
- show nodes
- snapshot list, manage, restore
- setup demo server
- instance (crud + terminal)
- projects view

0 comments on commit 4e6a3be

Please sign in to comment.