YunoHost/ynh-dev
1
0
Fork 0
mirror of https://github.com/YunoHost/ynh-dev.git synced 2024-09-03 20:05:59 +02:00
Code Issues Projects Releases Packages Wiki Activity

Readme coding style

Browse source
This commit is contained in:
Salamandar 2024-03-06 00:33:09 +01:00
parent be80111c61
commit 2ca61a909f
1 changed files with 68 additions and 70 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

138
README.md
View file

@ -1,34 +1,31 @@
# ynh-dev - Yunohost dev environment manager # ynh-dev - Yunohost dev environment manager
Please report issues on the following repository: Please report issues on the following repository: <https://github.com/yunohost/issues>
> https://github.com/yunohost/issues ## Table Of Contents
# Table Of Contents - [ynh-dev - Yunohost dev environment manager](#ynh-dev---yunohost-dev-environment-manager)
- [Table Of Contents](#table-of-contents)
- [Introduction](#introduction) - [Introduction](#introduction)
* [Local Development Path](#local-development-path) - [Local Development Path](#local-development-path)
* [Remote Development Path](#remote-development-path) - [Remote Development Path](#remote-development-path)
- [Local Development Environment](#local-development-environment)
- [Local Development Environment](#local-development-environment) - [1. Setup `ynh-dev` and the development environment](#1-setup-ynh-dev-and-the-development-environment)
* [1. Setup `ynh-dev` and the development environment](#1-setup-ynh-dev-and-the-development-environment) - [2. Manage YunoHost's dev LXCs](#2-manage-yunohosts-dev-lxcs)
* [2. Manage YunoHost's dev LXCs](#2-manage-yunohosts-dev-lxcs) - [3. Development and container testing](#3-development-and-container-testing)
* [3. Development and container testing](#3-development-and-container-testing) - [4. Testing the web interface](#4-testing-the-web-interface)
* [4. Testing the web interface](#4-testing-the-web-interface) - [Advanced: using snapshots](#advanced-using-snapshots)
* [Advanced: using snapshots](#advanced-using-snapshots) - [Alternative: Using Only Virtualbox](#alternative-using-only-virtualbox)
* [Alternative: Only Virtualbox](#alternative-using-only-virtualbox) - [Troubleshooting](#troubleshooting)
* [Troubleshooting](#troubleshooting) - [Remote Development Environment](#remote-development-environment)
- [1. Setup your VPS and install YunoHost](#1-setup-your-vps-and-install-yunohost)
- [Remote Development Environment](#remote-development-environment) - [2. Setup `ynh-dev` and the development environment](#2-setup-ynh-dev-and-the-development-environment)
* [1. Setup your VPS and install YunoHost](#1-setup-your-vps-and-install-yunohost) - [3. Develop and test](#3-develop-and-test)
* [2. Setup `ynh-dev` and the development environment](#2-setup-ynh-dev-and-the-development-environment) - [Further Resources](#further-resources)
* [3. Develop and test](#3-develop-and-test)
- [Further Resources](#further-resources)
--- ---
# Introduction ## Introduction
`ynh-dev` is a CLI tool to manage your local development environment for YunoHost. `ynh-dev` is a CLI tool to manage your local development environment for YunoHost.
@ -36,8 +33,8 @@ This allow you to develop on the various repositories of the YunoHost project.
In particular, it allows you to: In particular, it allows you to:
* Create a directory with a clone of each repository of the YunoHost project - Create a directory with a clone of each repository of the YunoHost project
* Replace Yunohost debian packages with symlinks to those git clones - Replace Yunohost debian packages with symlinks to those git clones
Because there are many diverse constraints on the development of the Yunohost Because there are many diverse constraints on the development of the Yunohost
project, there is no "official" one-size-fits-all development environment. project, there is no "official" one-size-fits-all development environment.
@ -49,15 +46,15 @@ your capacities and resources when aiming to setup a development environment.
`yhn-dev` can be used for the following scenarios: `yhn-dev` can be used for the following scenarios:
## Local Development Path ### Local Development Path
Yunohost can be developed on using a combination of the following technologies: Yunohost can be developed on using a combination of the following technologies:
* Git (any version is sufficient) - Git (any version is sufficient)
* LXD (>= 2.x) (though only tested with 3.x for now) - LXD (>= 2.x) (though only tested with 3.x for now)
Because LXC are containers, they are typically lightweight and quick to start and stop. Because LXC are containers, they are typically lightweight and quick to start and stop.
But you may find the initial setup complex (in particular network configuration). But you may find the initial setup complex (in particular network configuration).
LXD makes managing an LXC ecosystem much simpler. LXD makes managing an LXC ecosystem much simpler.
This local development path allows to work without an internet connection, This local development path allows to work without an internet connection,
@ -70,18 +67,18 @@ If choosing this path, please keep reading at the [local development
environment](#local-development-environment) section. environment](#local-development-environment) section.
Alternatively, you may be able to setup a local environnement using Vagrant and Alternatively, you may be able to setup a local environnement using Vagrant and
Virtualbox which is kinda more resource-hungry because it is fully virtualized, Virtualbox which is kinda more resource-hungry because it is fully virtualized,
but might be more familiar and user-friendly if you already know your way around but might be more familiar and user-friendly if you already know your way around
Virtualbox's UI. Virtualbox's UI.
* Virtualbox (>= 6.x) - Virtualbox (>= 6.x)
* Vagrant (>= ?.?.?) - Vagrant (>= ?.?.?)
* Vagrant-virtualbox (>= ?.?.?) - Vagrant-virtualbox (>= ?.?.?)
See the [Alternative: Only Virtualbox](#alternative-using-only-virtualbox) See the [Alternative: Only Virtualbox](#alternative-using-only-virtualbox)
section for more info. section for more info.
## Remote Development Path ### Remote Development Path
Yunohost can be deployed as a typical install on a remote VPS. You can then use Yunohost can be deployed as a typical install on a remote VPS. You can then use
`ynh-dev` to configure a development environment on the server. `ynh-dev` to configure a development environment on the server.
@ -89,7 +86,7 @@ Yunohost can be deployed as a typical install on a remote VPS. You can then use
This method can potentially be faster than the local development environment This method can potentially be faster than the local development environment
assuming you have familiarity with working on VPS machines, if you always have assuming you have familiarity with working on VPS machines, if you always have
internet connectivity when working, and if you're okay with paying a fee. It internet connectivity when working, and if you're okay with paying a fee. It
is also a good option if the required system dependencies (LXD/LXC, Vagrant, is also a good option if the required system dependencies (LXD/LXC, Vagrant,
Virtualbox, etc.) are not easily available to you on your distribution. Virtualbox, etc.) are not easily available to you on your distribution.
Please be aware that this method should **not** be used for a end-user facing Please be aware that this method should **not** be used for a end-user facing
@ -98,7 +95,7 @@ production environment.
If choosing this path, please keep reading at the [remote development If choosing this path, please keep reading at the [remote development
environment](#remote-development-environment) section. environment](#remote-development-environment) section.
# Local Development Environment ## Local Development Environment
Here is the development flow: Here is the development flow:
@ -106,13 +103,13 @@ Here is the development flow:
2. Manage YunoHost's development LXCs 2. Manage YunoHost's development LXCs
3. Develop on your local host and testing in the container 3. Develop on your local host and testing in the container
## 1. Setup `ynh-dev` and the development environment ### 1. Setup `ynh-dev` and the development environment
First you need to install the system dependencies. First you need to install the system dependencies.
`ynh-dev` essentially requires Git and the LXD/LXC ecosystem. Be careful that `ynh-dev` essentially requires Git and the LXD/LXC ecosystem. Be careful that
**LXD can conflict with other installed virtualization technologies such as **LXD can conflict with other installed virtualization technologies such as
libvirt or vanilla LXCs**, especially because they all require a daemon based libvirt or vanilla LXCs**, especially because they all require a daemon based
on DNSmasq and therefore require to listen on port 53. on DNSmasq and therefore require to listen on port 53.
On a Debian-based system (regular Debian, Ubuntu, Mint ...), LXD can be On a Debian-based system (regular Debian, Ubuntu, Mint ...), LXD can be
@ -125,9 +122,9 @@ apt install git snapd
sudo snap install core sudo snap install core
sudo snap install lxd sudo snap install lxd
# Adding lxc/lxd to /usr/local/bin to make sure we can use them easily even ## Adding lxc/lxd to /usr/local/bin to make sure we can use them easily even
# with sudo for which the PATH is defined in /etc/sudoers and probably doesn't ## with sudo for which the PATH is defined in /etc/sudoers and probably doesn't
# include /snap/bin ## include /snap/bin
sudo ln -s /snap/bin/lxc /usr/local/bin/lxc sudo ln -s /snap/bin/lxc /usr/local/bin/lxc
sudo ln -s /snap/bin/lxd /usr/local/bin/lxd sudo ln -s /snap/bin/lxd /usr/local/bin/lxd
``` ```
@ -149,10 +146,10 @@ On Archlinux-based distributions (Arch, Manjaro, ...) it was found that it's nee
that LXC/LXD will throw some error about "newuidmap failed to write mapping / Failed that LXC/LXD will throw some error about "newuidmap failed to write mapping / Failed
to set up id mapping" ... It can be [fixed with the following](https://discuss.linuxcontainers.org/t/solved-arch-linux-containers-only-run-when-security-privileged-true/4006/4) : to set up id mapping" ... It can be [fixed with the following](https://discuss.linuxcontainers.org/t/solved-arch-linux-containers-only-run-when-security-privileged-true/4006/4) :
``` ```bash
# N.B.: this is ONLY for Arch-based distros ## N.B.: this is ONLY for Arch-based distros
$ echo "root:1000000:65536" > /etc/subuid echo "root:1000000:65536" > /etc/subuid
$ echo "root:1000000:65536" > /etc/subgid echo "root:1000000:65536" > /etc/subgid
``` ```
Then, go into your favorite development folder and deploy `ynh-dev` with: Then, go into your favorite development folder and deploy `ynh-dev` with:
@ -167,15 +164,15 @@ In particular, you shall notice that there are clones or the various git
repositories. In the next step, we shall start a LXC and 'link' those folders repositories. In the next step, we shall start a LXC and 'link' those folders
between the host and the LXC. between the host and the LXC.
## 2. Manage YunoHost's dev LXCs ### 2. Manage YunoHost's dev LXCs
When ran on the host, the `./ynh-dev` command allows you to manage YunoHost's dev LXCs. When ran on the host, the `./ynh-dev` command allows you to manage YunoHost's dev LXCs.
Start your actual dev LXC using : Start your actual dev LXC using :
```bash ```bash
$ cd ynh-dev # if not already done cd ynh-dev # if not already done
$ ./ynh-dev start ./ynh-dev start
``` ```
This should automatically download from `devbaseimgs.yunohost.org` a pre-build ynh-dev LXC image running Yunohost unstable, and create a fresh container from it. This should automatically download from `devbaseimgs.yunohost.org` a pre-build ynh-dev LXC image running Yunohost unstable, and create a fresh container from it.
@ -184,7 +181,7 @@ After starting the LXC, your terminal will automatically be attached to it. If y
If you container **doesn't have an ip address nor access to internet**, this is likely because you either have a conflict with another virtualization system or that a program running on the host is using the port 53 and therefore prevent LXD's dnsmasq to run correctly (as stated before in the setup section.) If you container **doesn't have an ip address nor access to internet**, this is likely because you either have a conflict with another virtualization system or that a program running on the host is using the port 53 and therefore prevent LXD's dnsmasq to run correctly (as stated before in the setup section.)
## 3. Development and container testing ### 3. Development and container testing
After SSH-ing inside the container, you should notice that the *directory* `/ynh-dev` is a shared folder with your host. In particular, it contains the various git clones `yunohost`, `yunohost-admin` and so on - as well as the `./ynh-dev` script itself. After SSH-ing inside the container, you should notice that the *directory* `/ynh-dev` is a shared folder with your host. In particular, it contains the various git clones `yunohost`, `yunohost-admin` and so on - as well as the `./ynh-dev` script itself.
@ -195,7 +192,7 @@ Inside the container, `./ynh-dev` can be used to link the git clones living in t
For instance, after running: For instance, after running:
```bash ```bash
$ ./ynh-dev use-git yunohost ./ynh-dev use-git yunohost
``` ```
The code of the git clone `'yunohost'` will be directly available inside the container. Which mean that running any `yunohost` command inside the container will use the code from the host... This allows to develop with any tool you want on your host, then test the changes in the container. The code of the git clone `'yunohost'` will be directly available inside the container. Which mean that running any `yunohost` command inside the container will use the code from the host... This allows to develop with any tool you want on your host, then test the changes in the container.
@ -204,7 +201,7 @@ The `use-git` action can be used for any package among `yunohost`, `yunohost-adm
***Note***: The `use-git` operation can't be reverted now. Do **not** do this in production. ***Note***: The `use-git` operation can't be reverted now. Do **not** do this in production.
## 4. Testing the web interface ### 4. Testing the web interface
You should be able to access the web interface via the IP address of the container. The IP can be known from inside the container using either from `ip a` or with `./ynh-dev ip`. You should be able to access the web interface via the IP address of the container. The IP can be known from inside the container using either from `ip a` or with `./ynh-dev ip`.
@ -216,25 +213,26 @@ If you want to access to the interface using the domain name, you shall tweak yo
Note that `./ynh-dev use-git yunohost-admin` has a particular behavior: it starts a `gulp` watcher that shall re-compile automatically any changes in the javascript code. Hence this particular `use-git` will keep running until you kill it after your work is done. Note that `./ynh-dev use-git yunohost-admin` has a particular behavior: it starts a `gulp` watcher that shall re-compile automatically any changes in the javascript code. Hence this particular `use-git` will keep running until you kill it after your work is done.
## Advanced: using snapshots ### Advanced: using snapshots
You can check `lxc snapshot --help` to learn how to manage lxc snapshots. You can check `lxc snapshot --help` to learn how to manage lxc snapshots.
## Alternative: Using Only Virtualbox ### Alternative: Using Only Virtualbox
A Vagrant and Virtualbox (without LXC) guide is provided on another branch of A Vagrant and Virtualbox (without LXC) guide is provided on another branch of
this repository. This is a known working setup used by some developers. Please this repository. This is a known working setup used by some developers. Please
see the ["virtualbox" branch](https://github.com/YunoHost/ynh-dev/tree/virtualbox#develop-on-your-local-machine) see the ["virtualbox" branch](https://github.com/YunoHost/ynh-dev/tree/virtualbox#develop-on-your-local-machine)
for more. for more.
## Troubleshooting ### Troubleshooting
If you experiment network issues with your lxd during rebuild container steps. Probably your container are not able to get a local IP with DHCP. If you experiment network issues with your lxd during rebuild container steps. Probably your container are not able to get a local IP with DHCP.
It could be due to bridge conflict (for example if you have lxc installed too) or dnsmasq port already used. It could be due to bridge conflict (for example if you have lxc installed too) or dnsmasq port already used.
This [ticket](https://github.com/YunoHost/issues/issues/1664) could help. This [ticket](https://github.com/YunoHost/issues/issues/1664) could help.
# Remote Development Environment ## Remote Development Environment
Here is the development flow: Here is the development flow:
@ -242,36 +240,36 @@ Here is the development flow:
2. Setup `ynh-dev` and the development environment 2. Setup `ynh-dev` and the development environment
3. Develop and test 3. Develop and test
## 1. Setup your VPS and install YunoHost ### 1. Setup your VPS and install YunoHost
Setup a VPS somewhere (e.g. Scaleway, Digital Ocean, etc.) and install YunoHost following the [usual instructions](https://yunohost.org/#/install_manually). Setup a VPS somewhere (e.g. Scaleway, Digital Ocean, etc.) and install YunoHost following the [usual instructions](https://yunohost.org/#/install_manually).
Depending on what you want to achieve, you might want to run the postinstall right away - and/or setup a domain with an actually working DNS. Depending on what you want to achieve, you might want to run the postinstall right away - and/or setup a domain with an actually working DNS.
## 2. Setup `ynh-dev` and the development environment ### 2. Setup `ynh-dev` and the development environment
Deploy a `ynh-dev` folder at the root of the filesystem with: Deploy a `ynh-dev` folder at the root of the filesystem with:
``` ```bash
$ cd / cd /
$ curl https://raw.githubusercontent.com/yunohost/ynh-dev/master/deploy.sh | bash curl https://raw.githubusercontent.com/yunohost/ynh-dev/master/deploy.sh | bash
$ cd /ynh-dev cd /ynh-dev
``` ```
## 3. Develop and test ### 3. Develop and test
Inside the VPS, `./ynh-dev` can be used to link the git clones to actual the code being ran. Inside the VPS, `./ynh-dev` can be used to link the git clones to actual the code being ran.
For instance, after running: For instance, after running:
```bash ```bash
$ ./ynh-dev use-git yunohost ./ynh-dev use-git yunohost
``` ```
Any `yunohost` command will run from the code of the git clone. Any `yunohost` command will run from the code of the git clone.
The `use-git` action can be used for any package among `yunohost`, `yunohost-admin`, `moulinette` and `ssowat` with similar consequences. The `use-git` action can be used for any package among `yunohost`, `yunohost-admin`, `moulinette` and `ssowat` with similar consequences.
# Further Resources ## Further Resources
* [yunohost.org/dev](https://yunohost.org/dev) - [yunohost.org/dev](https://yunohost.org/dev)