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

Merge pull request #12 from YunoHost/enh-608-use-in-a-non-vagrant-instance

Browse source 
Explain how to use ynh-dev on an existing yunohost instance
This commit is contained in:
Zamentur aka ljf 2016-10-27 22:34:19 +02:00 committed by GitHub
commit 7a05e9222c
1 changed files with 142 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

173
README.md
View file

@ -3,16 +3,41 @@
This script is a Command line tool to manage your local development environement for YunoHost
With this you can develop on the unstable version of YunoHost quickly.
## Setup
This tool allow you:
### Install dependencies
* to create a directory with a clone of each repository
* to replace already installed yunohost debian packages by symlinks from those reporistories
* if needed, to manage yunohost instances on your host machine with vagrant by:
* creating yunohost vagrant vm
* sharing folder between your host and your yunohost vagrant vm (so you can develop directly on your host)
* finding the ip address of your yunohost vagrant vm
#### Debian, Ubuntu, Mint
There are 2 ways to use this tools:
1. on your host machine (more comfortable)
2. on an existing yunohost instance (for exemple if you need the vm is exposed on internet: test let's encrypt, test email ...)
## 1. Use this tool with your host machine
Here is the development flow:
1. [first time] Setup ynh-dev and Setup a copy of each git repository
2. Create or run a yunohost vagrant instance
3. Upgrade, postinstall and deploy development version from repositories
4. Code on your host
5. Test by cli on the instance or test on your host browser
6. Suspend or kill your vm
### 1.1 [first time] Setup ynh-dev and Setup a copy of each git repository
These operation need to be done on the host machine.
#### Install dependencies
##### Debian, Ubuntu, Mint
```shell
sudo apt-get install vagrant virtualbox git
```
#### Fedora
##### Fedora
```shell
sudo dnf install vagrant git
```
@ -20,55 +45,69 @@ sudo dnf install vagrant git
VirtualBox 5.1.4 only works with Vagrant ≥ 1.8.5. It could be installed from Fedora 25 or [rawhide](https://stackoverflow.com/a/24968411).
- [Install Virtualbox 5.1.x](http://www.if-not-true-then-false.com/2010/install-virtualbox-with-yum-on-fedora-centos-red-hat-rhel)
### Download ynh-dev script
#### Install ynh-dev
```shell
wget https://github.com/YunoHost/ynh-dev/raw/master/ynh-dev
chmod u+x ynh-dev
```
## Host usage
The `ynh-dev` tool provides 2 usefull command to run into your host machine. One
create a development environment by cloning Git repositories, the other one is a
helper to run a Vagrant virtual machine in the right place.
### Create the environment
#### Create the environment
This command create a clone of main git repositories and organize its.
```shell
./ynh-dev create-env /path/to/dev/env
```
### Run a container
### 1.2 Create or run a yunohost vagrant instance
This command is a helper to run a Vagrant virtual machine in the right place with YunoHost installed (but not postinstalled).
```shell
cd /path/to/dev/env
./ynh-dev run ynh.local testing
./ynh-dev run ynh.local unstable
```
The `run` command takes 2 arguments: domain and YunoHost version.
You'll be automatically logged in the VM through ssh.
After running the container, you'll be automatically logged inside a new yunohost VM or inside the previous suspended VM.
You probably want to run the postinstall now:
#### Sharing folder between host and virtual machines
(sudo) yunohost tools postinstall -d ynh.local
## Inside the Virtual machine (VM)
### Sharing folder between host and virtual machines
A shared folder between host and virtal machines could ease your development.
A shared folder between host and virtual machines could ease your development.
Once logged into your VM, go to `/vagrant` to enjoy folder sharing, and take
advantages of the `ynh-dev` script.
### Upgrade the container
### 1.3 Upgrade, postinstall and use git repositories
According to what you want to test or code, you could need to upgrade, to postinstall and to deploy core code in this order or no.
For example if you want :
* to test an app => upgrade and postinstall
* to test a common core code => upgrade, postinstall and deploy your code
* to test the impact of a core code on postinstall => upgrade, deploy your code, postinstall
#### Upgrade
May be the container is not up to date.
It will update every debian packages, including YunoHost ones.
```shell
/vagrant/ynh-dev upgrade
```
/vagrant/ynh-dev upgrade
You could need to update ynh-dev script, to do it:
```shell
/vagrant/ynh-dev self-update
```
### Use Git repositories
#### Postinstall
If it's a new yunohost container, you probably want to run the postinstall now:
```shell
(sudo) yunohost tools postinstall -d ynh.local
```
#### Use your git repositories in place of debian package
When doing `create-env` command, every YunoHost package have been cloned in the
corresponding path. Use these Git repositories inside the VM (with symlink).
@ -83,17 +122,89 @@ moulinette, yunohost-admin)
/vagrant/ynh-dev use-git PACKAGE_NAME
### 1.4 Code on your host
At this point, you are able to code on your host machine, with the EDI of your choice.
### Get ip address of your vm
All change will be available on the container inside the share folder /vagrant.
### 1.5 Test by cli on the instance or test on your host browser
#### Test by cli on the container
If you have run use-git, all change on core git repositories are automatically deployed on your container, so you can test your code.
#### Test on your host browser
If you want to test on your host browser, you need to know the ip addres.
You can get the ip address of your container by running this command inside the container
/vagrant/ynh-dev ip
Next, you just have to write the ip inside your browser.
### Update `ynh-dev` script
You probably want access by local domain name, to do that you can edit your /etc/hosts file to add a line like this:
/vagrant/ynh-dev self-update
IP_ADDRESS LOCAL_DOMAIN
### 1.6. Suspend or kill your vm
When you have finished or if you want to shut down you computer, you should kill or suspend the VM
To kill the vm, just do on your host:
```shell
cd /path/to/dev/env
vagrant destroy unstable
# or
./ynh-dev kill
```
To suspend the vm
```shell
cd /path/to/dev/env
vagrant suspend unstable
```
## 2. Directly on a YunoHost instance
Firstly, you need to understand that it is a dev tool, you shouldn't run it on a production environment !
This case allow you to use ynh-dev on a vm exposed on the internet.
It could be useful to develop code using external services which need to be able to reach your vm. Let's encrypt is a good example. An other way, is to use the first method with the vpnclient_ynh apps and a VPN with an ipv4 associated.
The development flow is quite similar to the first method:
1. [first time] Setup ynh-dev and Setup a copy of each git repository
2. Upgrade, postinstall and deploy development version from repositories
3. Code on your host
4. Test by cli on the instance or test on your host browser
### 2.1. Setup
It's possible to setup ynh-dev inside an existing instance of YunoHost rather than create vagrant vm with ynh-dev. In this particular case, you need to setup your env inside a /vagrant directory even if you don't use vagrant.
```shell
sudo apt-get install git
wget https://github.com/YunoHost/ynh-dev/raw/master/ynh-dev
chmod u+x ynh-dev
./ynh-dev create-env /vagrant
```
### 2.2 Upgrade, postinstall and use git repositories
Identical to 1.3, but take care to don't postinstall on a yunohost already postinstalled !
Important, when you use the git repositories, you can't do the reverse operation simply... (To do it you need to wait an update of the concern package)
### 2.3 Code on the instance directly
Contrary to the first method, you have not a share folder so you need to develop inside the instance. Alternatively, you could explore to setup sshfs or this kind of solution.
### 2.4 Test
Identical to 1.5, but ynh-dev ip doesn't work. You should prefer this command to find your ip address:
ip addr
Keep in mind, that if you use your /etc/hosts file, let's encrypt or other service couldn't access the VM. So you probably need to set up a correct domain.
## More info
## More info
[yunohost.org/dev_fr](https://yunohost.org/dev_fr) (in french) not up-to-date.