{"id":14155199,"url":"https://github.com/YunoHost/ynh-dev","last_synced_at":"2025-08-06T01:30:40.809Z","repository":{"id":44884510,"uuid":"44062591","full_name":"YunoHost/ynh-dev","owner":"YunoHost","description":"Dev environement wrapper, based on Incus, to develop on YunoHost","archived":false,"fork":false,"pushed_at":"2024-06-05T09:02:23.000Z","size":283,"stargazers_count":36,"open_issues_count":3,"forks_count":28,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-08-17T08:04:50.840Z","etag":null,"topics":["dev-environnement","developer-tools","devtool","incus","lxc","virtualbox","ynh-dev","yunohost"],"latest_commit_sha":null,"homepage":"https://yunohost.org/dev","language":"Shell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YunoHost.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-11T17:41:59.000Z","updated_at":"2024-08-01T18:00:50.000Z","dependencies_parsed_at":"2024-04-28T21:24:34.354Z","dependency_job_id":"ee84d62a-de15-4825-a6e0-e687c84f0e62","html_url":"https://github.com/YunoHost/ynh-dev","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YunoHost%2Fynh-dev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YunoHost%2Fynh-dev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YunoHost%2Fynh-dev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YunoHost%2Fynh-dev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YunoHost","download_url":"https://codeload.github.com/YunoHost/ynh-dev/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228821400,"owners_count":17977165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dev-environnement","developer-tools","devtool","incus","lxc","virtualbox","ynh-dev","yunohost"],"created_at":"2024-08-17T08:02:28.124Z","updated_at":"2024-12-09T02:31:06.616Z","avatar_url":"https://github.com/YunoHost.png","language":"Shell","readme":"# ynh-dev - Yunohost dev environment manager\n\nPlease report issues on the following repository: \u003chttps://github.com/yunohost/issues\u003e\n\n## Table Of Contents\n\n- [ynh-dev - Yunohost dev environment manager](#ynh-dev---yunohost-dev-environment-manager)\n  - [Table Of Contents](#table-of-contents)\n  - [Introduction](#introduction)\n    - [Local Development Path](#local-development-path)\n    - [Remote Development Path](#remote-development-path)\n  - [Local Development Environment](#local-development-environment)\n    - [1. Setup `ynh-dev` and the development environment](#1-setup-ynh-dev-and-the-development-environment)\n    - [2. Manage YunoHost's dev LXCs](#2-manage-yunohosts-dev-lxcs)\n    - [3. Development and container testing](#3-development-and-container-testing)\n    - [4. Testing the web interface](#4-testing-the-web-interface)\n    - [Advanced: using snapshots](#advanced-using-snapshots)\n    - [Troubleshooting](#troubleshooting)\n  - [Remote Development Environment](#remote-development-environment)\n    - [1. Setup your VPS and install YunoHost](#1-setup-your-vps-and-install-yunohost)\n    - [2. Setup `ynh-dev` and the development environment](#2-setup-ynh-dev-and-the-development-environment)\n    - [3. Develop and test](#3-develop-and-test)\n  - [Further Resources](#further-resources)\n\n---\n\n## Introduction\n\n`ynh-dev` is a CLI tool to manage your local development environment for YunoHost.\n\nThis allow you to develop on the various repositories of the YunoHost project.\n\nIn particular, it allows you to:\n\n- Create a directory with a clone of each repository of the YunoHost project\n- Replace Yunohost debian packages with symlinks to those git clones\n\nBecause there are many diverse constraints on the development of the Yunohost\nproject, there is no \"official\" one-size-fits-all development environment.\nHowever, we do provide documentation for what developers are using now in\nvarious circumstances.\n\nPlease keep this in mind when reviewing the following options with regard to\nyour capacities and resources when aiming to setup a development environment.\n\n`yhn-dev` can be used for the following scenarios:\n\n### Local Development Path\n\nYunohost can be developed on using a combination of the following technologies:\n\n- Git (any version is sufficient)\n- Incus\n\nBecause LXC are containers, they are typically lightweight and quick to start and stop.\nBut you may find the initial setup complex (in particular network configuration).\nIncus makes managing an LXC ecosystem much simpler.\n\nThis local development path allows to work without an internet connection,\nbut be aware that it will *not* allow you to easily test your email stack\nor deal with deploying SSL certificates, for example, as your machine is\nlikely to not be exposed on the internet. A remote machine should be used\nfor these cases.\n\nIf choosing this path, please keep reading at the [local development\nenvironment](#local-development-environment) section.\n\n### Remote Development Path\n\nYunohost can be deployed as a typical install on a remote VPS. You can then use\n`ynh-dev` to configure a development environment on the server.\n\nThis method can potentially be faster than the local development environment\nassuming you have familiarity with working on VPS machines, if you always have\ninternet connectivity when working, and if you're okay with paying a fee. It\nis also a good option if the required system dependencies (Incus/LXC, Virtualbox,\netc.) are not easily available to you on your distribution.\n\nPlease be aware that this method should **not** be used for a end-user facing\nproduction environment.\n\nIf choosing this path, please keep reading at the [remote development\nenvironment](#remote-development-environment) section.\n\n## Local Development Environment\n\nHere is the development flow:\n\n1. Setup `ynh-dev` and the development environment\n2. Manage YunoHost's development LXCs\n3. Develop on your local host and testing in the container\n\n### 1. Setup `ynh-dev` and the development environment\n\nFirst you need to install the system dependencies.\n\n`ynh-dev` essentially requires Git and the Incus/LXC ecosystem. Be careful that\n**Incus/LXC can conflict with other installed virtualization technologies such as\nlibvirt or vanilla LXCs**, especially because they all require a daemon based\non DNSmasq and therefore require to listen on port 53.\n\nIncus can be installed on Debian 13 or Ubuntu 24.04 with the following command:\n\n```bash\napt install incus\n```\n\nIf you have an older distribution, you need to add the Zabbly repository to your package manager.  \nTo do so please follow the installation guide that you can find on \u003chttps://github.com/zabbly/incus\u003e.\n\nYou then need to add yourself in the incus-admin group, to run incus without sudo every time:\n\n```bash\nsudo usermod -a -G incus-admin $(whoami)\n```\n\nNow the group incus-admin should be present when you type the command:\n\n```bash\ngroups\n```\n\nIf not you need to create the group first:\n\n```bash\nnewgrp incus-admin\nsudo usermod -a -G incus-admin $(whoami)\n```\n\nThen you shall initialize Incus which will ask you a bunch of question. Usually\nanswering the default (just pressing enter) to all questions is fine.\n\n```bash\nincus admin init\n```\n\nPre-built images are centralized on `https://repo.yunohost.org/incus` and we'll download them from there to speed things up:\n\n```bash\nincus remote add yunohost https://repo.yunohost.org/incus --protocol simplestreams --public\n```\n\nOn Archlinux-based distributions (Arch, Manjaro, ...) it was found that it's needed\nthat Incus/LXC will throw some error about \"newuidmap failed to write mapping / Failed\nto 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\n```bash\n## N.B.: this is ONLY for Arch-based distros\necho \"root:1000000:65536\" \u003e /etc/subuid\necho \"root:1000000:65536\" \u003e /etc/subgid\n```\n\nThen, go into your favorite development folder and deploy `ynh-dev` with:\n\n```bash\ncurl https://raw.githubusercontent.com/yunohost/ynh-dev/master/deploy.sh | bash\n```\n\nThis will create a new `ynh-dev` folder with everything you need inside.\n\nIn particular, you shall notice that there are clones or the various git\nrepositories. In the next step, we shall start a LXC and 'link' those folders\nbetween the host and the LXC.\n\n### 2. Manage YunoHost's dev LXCs\n\nWhen ran on the host, the `./ynh-dev` command allows you to manage YunoHost's dev LXCs.\n\nStart your actual dev LXC using :\n\n```bash\ncd ynh-dev  # if not already done\n./ynh-dev start\n```\n\nThis should automatically download from `https://repo.yunohost.org/incus` a pre-build\nynh-dev LXC image running Yunohost unstable, and create a fresh container from it.\n\nAfter starting the LXC, your terminal will automatically be attached to it. If you\nlater disconnect from the LXC, you can go back in with `./ynh-dev attach`. Later,\nyou might want to destroy the LXC. You can do so with `./ynh-dev destroy`.\n\nIf you container **doesn't have an ip address nor access to internet**, this is\nlikely because you either have a conflict with another virtualization system or\nthat a program running on the host is using the port 53 and therefore prevent\nIncus's dnsmasq to run correctly (as stated before in the setup section.)\n\n### 3. Development and container testing\n\nAfter SSH-ing inside the container, you should notice that the *directory* `/ynh-dev` is a shared folder with your host.\nIn particular, it contains the various git clones `yunohost`, `yunohost-admin` and so on - as well as the `./ynh-dev` script itself.\n\n**Most of the time, the first thing you'll want to do is to start by running `yunohost tools postinstall` as the first command**\n(except if you are working on something that happens before the postinstall).\n\nInside the container, `./ynh-dev` can be used to link the git clones living in the host to the code being ran inside the container.\n\nFor instance, after running:\n\n```bash\n./ynh-dev use-git yunohost\n```\n\nThe code of the git clone `'yunohost'` will be directly available inside the container.\nWhich mean that running any `yunohost` command inside the container will use the code from the host...\nThis allows to develop with any tool you want on your host, then test the changes in the container.\n\nThe `use-git` action can be used for any package among `yunohost`, `yunohost-admin`, `moulinette` and `ssowat` with similar consequences.\nYou might want to run use-git several times depending on what you want to develop precisely.\n\nWhen using `use-git` on package `yunohost`, please do it also on its dependency package `moulinette`.\nBoth packages should be on branch `bookworm`.\n\n***Note***: The `use-git` operation can't be reverted now. Do **not** do this in production.\n\n### 4. Testing the web interface\n\nYou should be able to access the web interface via the IP address of the container.\nThe IP can be known from inside the container using either from `ip a` or with `./ynh-dev ip`.\n\nIf you want to access to the interface using the domain name, you shall tweak your `/etc/hosts` and add a line such as:\n\n```bash\n111.222.333.444 yolo.test\n```\n\nNote that `./ynh-dev use-git yunohost-admin` has a particular behavior: it starts a `gulp` watcher\nthat shall re-compile automatically any changes in the javascript code. Hence this particular `use-git`\nwill keep running until you kill it after your work is done.\n\n### Advanced: using snapshots\n\nYou can check `incus snapshot --help` to learn how to manage incus snapshots.\n\n### Troubleshooting\n\nIf you experiment network issues with your incus during rebuild container steps. Probably your container are not able to get a local IP with DHCP.\n\nIt could be due to bridge conflict (for example if you have incus installed too) or dnsmasq port already used.\n\nThis [ticket](https://github.com/YunoHost/issues/issues/1664) could help.\n\nIf you have docker and incus, and your dns resolution inside incus container does not work at all, you can try:\n```\nsudo iptables -I DOCKER-USER -i incusbr0 -o eno1 -j ACCEPT\n```\n\n## Remote Development Environment\n\nHere is the development flow:\n\n1. Setup your VPS and install YunoHost\n2. Setup `ynh-dev` and the development environment\n3. Develop and test\n\n### 1. Setup your VPS and install YunoHost\n\nSetup a VPS somewhere (e.g. Scaleway, Digital Ocean, etc.) and install YunoHost following the [usual instructions](https://yunohost.org/#/install_manually).\n\nDepending 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.\n\n### 2. Setup `ynh-dev` and the development environment\n\nDeploy a `ynh-dev` folder at the root of the filesystem with:\n\n```bash\ncd /\ncurl https://raw.githubusercontent.com/yunohost/ynh-dev/master/deploy.sh | bash\ncd /ynh-dev\n```\n\n### 3. Develop and test\n\nInside the VPS, `./ynh-dev` can be used to link the git clones to actual the code being ran.\n\nFor instance, after running:\n\n```bash\n./ynh-dev use-git yunohost\n```\n\nAny `yunohost` command will run from the code of the git clone.\n\nThe `use-git` action can be used for any package among `yunohost`, `yunohost-admin`, `moulinette` and `ssowat` with similar consequences.\n\n## Further Resources\n\n- [yunohost.org/dev](https://yunohost.org/dev)\n","funding_links":[],"categories":["developer-tools"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYunoHost%2Fynh-dev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYunoHost%2Fynh-dev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYunoHost%2Fynh-dev/lists"}