mirror of
https://github.com/YunoHost/ynh-dev.git
synced 2024-09-03 20:05:59 +02:00
Readme coding style
This commit is contained in:
parent
be80111c61
commit
2ca61a909f
1 changed files with 68 additions and 70 deletions
138
README.md
138
README.md
|
|
@ -1,34 +1,31 @@
|
|||
# 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
|
||||
|
||||
- [Introduction](#introduction)
|
||||
* [Local Development Path](#local-development-path)
|
||||
* [Remote Development Path](#remote-development-path)
|
||||
|
||||
- [Local Development Environment](#local-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)
|
||||
* [3. Development and container testing](#3-development-and-container-testing)
|
||||
* [4. Testing the web interface](#4-testing-the-web-interface)
|
||||
* [Advanced: using snapshots](#advanced-using-snapshots)
|
||||
* [Alternative: Only Virtualbox](#alternative-using-only-virtualbox)
|
||||
* [Troubleshooting](#troubleshooting)
|
||||
|
||||
- [Remote Development Environment](#remote-development-environment)
|
||||
* [1. Setup your VPS and install YunoHost](#1-setup-your-vps-and-install-yunohost)
|
||||
* [2. Setup `ynh-dev` and the development environment](#2-setup-ynh-dev-and-the-development-environment)
|
||||
* [3. Develop and test](#3-develop-and-test)
|
||||
|
||||
- [Further Resources](#further-resources)
|
||||
- [ynh-dev - Yunohost dev environment manager](#ynh-dev---yunohost-dev-environment-manager)
|
||||
- [Table Of Contents](#table-of-contents)
|
||||
- [Introduction](#introduction)
|
||||
- [Local Development Path](#local-development-path)
|
||||
- [Remote Development Path](#remote-development-path)
|
||||
- [Local Development Environment](#local-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)
|
||||
- [3. Development and container testing](#3-development-and-container-testing)
|
||||
- [4. Testing the web interface](#4-testing-the-web-interface)
|
||||
- [Advanced: using snapshots](#advanced-using-snapshots)
|
||||
- [Alternative: Using Only Virtualbox](#alternative-using-only-virtualbox)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Remote Development Environment](#remote-development-environment)
|
||||
- [1. Setup your VPS and install YunoHost](#1-setup-your-vps-and-install-yunohost)
|
||||
- [2. Setup `ynh-dev` and the development environment](#2-setup-ynh-dev-and-the-development-environment)
|
||||
- [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.
|
||||
|
||||
|
|
@ -36,8 +33,8 @@ This allow you to develop on the various repositories of the YunoHost project.
|
|||
|
||||
In particular, it allows you to:
|
||||
|
||||
* Create a directory with a clone of each repository of the YunoHost project
|
||||
* Replace Yunohost debian packages with symlinks to those git clones
|
||||
- Create a directory with a clone of each repository of the YunoHost project
|
||||
- Replace Yunohost debian packages with symlinks to those git clones
|
||||
|
||||
Because there are many diverse constraints on the development of the Yunohost
|
||||
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:
|
||||
|
||||
## Local Development Path
|
||||
### Local Development Path
|
||||
|
||||
Yunohost can be developed on using a combination of the following technologies:
|
||||
|
||||
* Git (any version is sufficient)
|
||||
* LXD (>= 2.x) (though only tested with 3.x for now)
|
||||
- Git (any version is sufficient)
|
||||
- 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.
|
||||
But you may find the initial setup complex (in particular network configuration).
|
||||
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).
|
||||
LXD makes managing an LXC ecosystem much simpler.
|
||||
|
||||
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.
|
||||
|
||||
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,
|
||||
but might be more familiar and user-friendly if you already know your way around
|
||||
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
|
||||
Virtualbox's UI.
|
||||
|
||||
* Virtualbox (>= 6.x)
|
||||
* Vagrant (>= ?.?.?)
|
||||
* Vagrant-virtualbox (>= ?.?.?)
|
||||
- Virtualbox (>= 6.x)
|
||||
- Vagrant (>= ?.?.?)
|
||||
- Vagrant-virtualbox (>= ?.?.?)
|
||||
|
||||
See the [Alternative: Only Virtualbox](#alternative-using-only-virtualbox)
|
||||
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
|
||||
`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
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
environment](#remote-development-environment) section.
|
||||
|
||||
# Local Development Environment
|
||||
## Local Development Environment
|
||||
|
||||
Here is the development flow:
|
||||
|
||||
|
|
@ -106,13 +103,13 @@ Here is the development flow:
|
|||
2. Manage YunoHost's development LXCs
|
||||
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.
|
||||
|
||||
`ynh-dev` essentially requires Git and the LXD/LXC ecosystem. Be careful that
|
||||
**LXD can conflict with other installed virtualization technologies such as
|
||||
libvirt or vanilla LXCs**, especially because they all require a daemon based
|
||||
`ynh-dev` essentially requires Git and the LXD/LXC ecosystem. Be careful that
|
||||
**LXD can conflict with other installed virtualization technologies such as
|
||||
libvirt or vanilla LXCs**, especially because they all require a daemon based
|
||||
on DNSmasq and therefore require to listen on port 53.
|
||||
|
||||
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 lxd
|
||||
|
||||
# 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
|
||||
# include /snap/bin
|
||||
## 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
|
||||
## include /snap/bin
|
||||
sudo ln -s /snap/bin/lxc /usr/local/bin/lxc
|
||||
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
|
||||
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) :
|
||||
|
||||
```
|
||||
# N.B.: this is ONLY for Arch-based distros
|
||||
$ echo "root:1000000:65536" > /etc/subuid
|
||||
$ echo "root:1000000:65536" > /etc/subgid
|
||||
```bash
|
||||
## N.B.: this is ONLY for Arch-based distros
|
||||
echo "root:1000000:65536" > /etc/subuid
|
||||
echo "root:1000000:65536" > /etc/subgid
|
||||
```
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
Start your actual dev LXC using :
|
||||
|
||||
```bash
|
||||
$ cd ynh-dev # if not already done
|
||||
$ ./ynh-dev start
|
||||
cd ynh-dev # if not already done
|
||||
./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.
|
||||
|
|
@ -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.)
|
||||
|
||||
## 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.
|
||||
|
||||
|
|
@ -195,7 +192,7 @@ Inside the container, `./ynh-dev` can be used to link the git clones living in t
|
|||
For instance, after running:
|
||||
|
||||
```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.
|
||||
|
|
@ -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.
|
||||
|
||||
## 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`.
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
## Advanced: using snapshots
|
||||
### Advanced: using 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
|
||||
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)
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
# Remote Development Environment
|
||||
## Remote Development Environment
|
||||
|
||||
Here is the development flow:
|
||||
|
||||
|
|
@ -242,36 +240,36 @@ Here is the development flow:
|
|||
2. Setup `ynh-dev` and the development environment
|
||||
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).
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
$ cd /
|
||||
$ curl https://raw.githubusercontent.com/yunohost/ynh-dev/master/deploy.sh | bash
|
||||
$ cd /ynh-dev
|
||||
```bash
|
||||
cd /
|
||||
curl https://raw.githubusercontent.com/yunohost/ynh-dev/master/deploy.sh | bash
|
||||
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.
|
||||
|
||||
For instance, after running:
|
||||
|
||||
```bash
|
||||
$ ./ynh-dev use-git yunohost
|
||||
./ynh-dev use-git yunohost
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
# Further Resources
|
||||
## Further Resources
|
||||
|
||||
* [yunohost.org/dev](https://yunohost.org/dev)
|
||||
- [yunohost.org/dev](https://yunohost.org/dev)
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue