-
Fork the repository
-
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
-
Setup LXD as a backend:
Setup LXD - Linux (with snap)
snap install lxd lxd init # can accept all defaults lxc config set core.https_address "[::]:8443" lxc config set user.show_permissions=true
Setup LXD - Mac
⚠️ 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.
Then install LXC client with brew:
brew install lxc
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
Once you have LXC and Multipass installed, we can create a Multipass instance where we will run the LXD daemon:
# 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
If you get the
Launched: lxd
output, it means that the command succeeded. We can now launch a shell into the newly created instance:multipass shell lxd
You should be greeted with the Ubuntu shell login message
Welcome to Ubuntu ...
. Make sure the latest version of LXD is installed:sudo snap refresh lxd --channel=latest/stable
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:sudo lxd init --auto --trust-password your-password --network-address '[::]' exit
Connect the LXD server in Multipass to the local LXC. In a terminal on your Mac, run:
lxc remote add default $(multipass info lxd | grep IPv4 | awk '{print $2}') --password your-password --accept-certificate
(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:lxc remote switch default
Launch an instance with the lxc command on your Mac:
lxc launch ubuntu:jammy test-jammy
If this succeeds, the setup of LXC and LXD is complete. Finally, expose the API on port 8443:
lxc config set core.https_address "[::]:8443"
-
Install dotrun 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 port8407
. Ensure that the lxd API on port8443
is open, sodotrun
can access it.The first time, running
dotrun
will generate certificates for you. You can find them in thekeys
folder on the top level of the repo. Trust them from your locallxc
withsudo 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
, executeyarn hooks-add
. To remove them, runyarn hooks-remove
. -
Create a new topic branch:
git checkout -b my-topic-branch
-
Make changes, commit, and push to your fork:
git push -u origin HEAD
-
Go to the repository 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.
All contributors must sign the Canonical contributor license agreement, which gives Canonical permission to use the contributions. The author of a change remains the copyright holder of their code (no copyright assignment).
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.
- Generating a new GPG key or use an existing GPG key. 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.
- Add a GPG key to your Github account. This will make your commits verified on Github.
- 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"
. - 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 withgit sc -m "initial commit"
for example. Note this only enables the alias for your local git configuration.
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:
- 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 theGET /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 usefuluseSupportedFeatures
hook can be used for this purpose. You can also find a comprehensive list ofapi_extensions
refrences in the lxd documentation. - 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.
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
Generate new tests with helper Doc
npx playwright codegen --ignore-https-errors https://localhost:8407/
Explore and debug tests in UI mode Doc
npx playwright test --ui
Learn more about the test architecture in our architecture documentation.
Learn how to
- Setup local LXD cluster inside LXD to enable clustering features
- Setup oidc login to enable SSO authentication
- See Architecture for details on the dev setup.