LICENSE

@@ -1 +1,4 @@
-AGPL-3
+File containing the license of your package.
+
+More information here:
+https://choosealicense.com/

conf/.env

@@ -1,15 +0,0 @@
-APP_NAME="My Idlers"
-APP_ENV=production
-APP_KEY=
-APP_DEBUG=false
-APP_URL=https://__DOMAIN__
-
-
-DB_CONNECTION=mysql
-DB_HOST=127.0.0.1
-DB_PORT=3306
-DB_DATABASE=__DB_NAME__
-DB_USERNAME=__DB_USER__
-DB_PASSWORD=__DB_PWD__
-DB_LOG_SQL=false
-

conf/nginx.conf

@@ -1,33 +1,25 @@
-server {
+#sub_path_only rewrite ^__PATH__$ __PATH__/ permanent;
-    listen 80;
+location __PATH__/ {
-    server_name __DOMAIN_NAME__;
-    root /example.com/public;
 
-    add_header X-Frame-Options "SAMEORIGIN";
+  # Path to source
-    add_header X-XSS-Protection "1; mode=block";
+  alias __INSTALL_DIR__/;
-    add_header X-Content-Type-Options "nosniff";
 
-    index index.html index.htm index.php;
+### Example PHP configuration (remove it if not used)
+  index index.php;
 
-    charset utf-8;
+  # Common parameter to increase upload size limit in conjunction with dedicated PHP-FPM file
+  # client_max_body_size 50M;
 
-    location / {
+  try_files $uri $uri/ index.php;
-        try_files $uri $uri/ /index.php?$query_string;
+  location ~ [^/]\.php(/|$) {
-    }
+    fastcgi_split_path_info ^(.+?\.php)(/.*)$;
+    fastcgi_pass unix:/var/run/php/php__PHP_VERSION__-fpm-__APP__.sock;
 
-    location = /favicon.ico { access_log off; log_not_found off; }
-    location = /robots.txt  { access_log off; log_not_found off; }
-
-    error_page 404 /index.php;
-
-    location ~ \.php$ {
-        fastcgi_pass unix:/var/run/php__PHP_VERSION__-fpm.sock;
     fastcgi_index index.php;
-        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
     include fastcgi_params;
+    fastcgi_param REMOTE_USER $remote_user;
+    fastcgi_param PATH_INFO $fastcgi_path_info;
+    fastcgi_param SCRIPT_FILENAME $request_filename;
   }
-
+### End of PHP configuration part
-    location ~ /\.(?!well-known).* {
-        deny all;
-    }
 }

conf/systemd.service

@@ -0,0 +1,49 @@
+[Unit]
+Description=Small description of the service
+After=network.target
+
+[Service]
+Type=simple
+User=__APP__
+Group=__APP__
+WorkingDirectory=__INSTALL_DIR__/
+ExecStart=__INSTALL_DIR__/script
+StandardOutput=append:/var/log/__APP__/__APP__.log
+StandardError=inherit
+
+### Depending on specificities of your service/app, you may need to tweak these
+### .. but this should be a good baseline
+# Sandboxing options to harden security
+# Details for these options: https://www.freedesktop.org/software/systemd/man/systemd.exec.html
+NoNewPrivileges=yes
+PrivateTmp=yes
+PrivateDevices=yes
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
+RestrictNamespaces=yes
+RestrictRealtime=yes
+DevicePolicy=closed
+ProtectClock=yes
+ProtectHostname=yes
+ProtectProc=invisible
+ProtectSystem=full
+ProtectControlGroups=yes
+ProtectKernelModules=yes
+ProtectKernelTunables=yes
+LockPersonality=yes
+SystemCallArchitectures=native
+SystemCallFilter=~@clock @debug @module @mount @obsolete @reboot @setuid @swap @cpu-emulation @privileged
+
+# Denying access to capabilities that should not be relevant for webapps
+# Doc: https://man7.org/linux/man-pages/man7/capabilities.7.html
+CapabilityBoundingSet=~CAP_RAWIO CAP_MKNOD
+CapabilityBoundingSet=~CAP_AUDIT_CONTROL CAP_AUDIT_READ CAP_AUDIT_WRITE
+CapabilityBoundingSet=~CAP_SYS_BOOT CAP_SYS_TIME CAP_SYS_MODULE CAP_SYS_PACCT
+CapabilityBoundingSet=~CAP_LEASE CAP_LINUX_IMMUTABLE CAP_IPC_LOCK
+CapabilityBoundingSet=~CAP_BLOCK_SUSPEND CAP_WAKE_ALARM
+CapabilityBoundingSet=~CAP_SYS_TTY_CONFIG
+CapabilityBoundingSet=~CAP_MAC_ADMIN CAP_MAC_OVERRIDE
+CapabilityBoundingSet=~CAP_NET_ADMIN CAP_NET_BROADCAST CAP_NET_RAW
+CapabilityBoundingSet=~CAP_SYS_ADMIN CAP_SYS_PTRACE CAP_SYSLOG
+
+[Install]
+WantedBy=multi-user.target

doc/DESCRIPTION.md

@@ -1,22 +1 @@
-If you are the person in your family, group of friends or colleauges that manages the servers, domain names, online accounts and other hosted services, than this app is for you. 
+This is a dummy description of this app features
-
-My Idlers is a useful register for keeping track of your servers and online hosting accounts. 
-
-It is a single-user app; if more than one person wants to use this functionality, it needs to be installed multiple times. 
-Besides that, for now, it needs a (sub)domain for itself. 
-
-This is my first app packaging attempt; there may be some rough edges. 
-
-What works: 
-* installing the app and using its features
-* uninstalling 
-* backup
-* moving the app to another domain
-
-What does not (yet?) work or is untested:
-* installing the app in subfolder
-* LDAP integration
-* restore from backup 
-* API access 
-
-![Screenshot of My Idlers](./doc/screenshots/my_idlers.jpg)

doc/DESCRIPTION_fr.md

@@ -1,24 +1 @@
-(machine translate from English) 
+Ceci est une fausse description des fonctionalités de l'app
-
-Si vous êtes la personne de votre famille, de votre groupe d'amis ou de vos collègues qui gère les serveurs, les noms de domaine, les comptes en ligne et d'autres services hébergés, alors cette application est faite pour vous.
-
-My Idlers est un registre utile pour suivre vos serveurs et vos comptes d'hébergement en ligne.
-
-C'est une application monoposte; si plusieurs personnes veulent utiliser cette fonctionnalité, il faut l'installer plusieurs fois. De plus, pour l'instant, elle nécessite un (sous-)domaine dédié.
-
-Il s'agit de ma première tentative d'emballage d'application; il peut y avoir quelques imperfections.
-
-Ce qui fonctionne :
-* installation de l'application et utilisation de ses fonctionnalités
-* désinstallation
-* sauvegarde
-* déplacement de l'application vers un autre domaine
-
-Ce qui ne fonctionne pas (encore) ou n'est pas testé :
-* installation de l'application dans un sous-dossier
-* intégration LDAP
-* restauration à partir d'une sauvegarde
-* accès API
-
-    
-![Screenshot of My Idlers](./doc/screenshots/my_idlers.jpg)

doc/POST_INSTALL.md

@@ -1,7 +1,7 @@
+This is a dummy disclaimer to display after the install
+
 The app url is <https://__DOMAIN____PATH__>
 
 The app install dir is `__INSTALL_DIR__`
 
 The app id is `__ID__`
-
-There was an attempt to create a user with the credentials you provided. Please open the app to log in. If presented with a "registration" page instead of "login", please create an account yourself. Either way, the account will unfortunately not be synchronized with Yunohost users. 

doc/PRE_INSTALL.md

@@ -1,3 +1 @@
-For now, only the domain and group can be set. 
+This is a dummy disclaimer to display prior to the install
-
-After installation, visit the app to create an account. As this is a single-user app, the registration page will not be available after that anymore.

doc/PRE_INSTALL_fr.md

@@ -1,3 +1 @@
-Pour l'instant, seuls le domaine et le groupe peuvent être définis.
+Ceci est un faux disclaimer à présenter avant l'installation
-
-Après l'installation, visitez l'application pour créer un compte. Comme il s'agit d'une application monoposte, la page de création de compte ne sera plus disponible par la suite.

manifest.toml

@@ -2,80 +2,135 @@
 
 packaging_format = 2
 
-id = "my_idlers"
+id = "example"
-name = "My Idlers"
+name = "Example app"
-description.en = "A self-hosted web app for displaying, organizing and storing information about your servers (VPS/Dedi), shared & reseller hosting, seedboxes, domains, DNS and misc services. Are you the person in your family, group of friends or at work who keeps an eye on everyones Yunohosts, then this is the app to help you."
+description.en = "Explain in *a few (10~15) words* the purpose of the app or what it actually does (it is meant to give a rough idea to users browsing a catalog of 100+ apps)"
-description.fr = "Une application Web auto-hébergée pour afficher, organiser et stocker des informations sur vos serveurs (VPS/Dedi), votre hébergement partagé et revendeur, vos seedboxes, vos domaines, vos DNS et divers services."
+description.fr = "Expliquez en *quelques* (10~15) mots l'utilité de l'app ou ce qu'elle fait (l'objectif est de donner une idée grossière pour des utilisateurs qui naviguent dans un catalogue de 100+ apps)"
 
-version = "3.0~ynh1"
+version = "1.0~ynh1"
 
-maintainers = ["wbk"]
+maintainers = ["johndoe"]
 
 [upstream]
-license = "MIT" 
+# NB: Only the "license" key is mandatory. Remove entries for which there's no relevant data
-demo    = "https://demo.myidlers.com/login"
+license = "free" # you can see the available licenses identifiers list here: https://spdx.org/licenses/
-userdoc = "https://lowendspirit.com/discussion/2449/my-idlers-self-hosted-web-app-for-your-servers-shared-hosting-and-domains-information/"
+website = "https://example.com"
-code    = "https://github.com/cp6/my-idlers#install"
+demo = "https://demo.example.com"
+admindoc = "https://yunohost.org/packaging_apps"
+userdoc = "https://yunohost.org/apps"
+code = "https://some.forge.com/example/example"
+# FIXME: optional but recommended if relevant, this is meant to contain the Common Platform Enumeration, which is
+# sort of a standard id for applications defined by the NIST. In particular, YunoHost may use this is in the future
+# to easily track CVE (=security reports) related to apps. The CPE may be obtained by searching here:
+# https://nvd.nist.gov/products/cpe/search.
+# For example, for Nextcloud, the CPE is 'cpe:2.3:a:nextcloud:nextcloud' (no need to include the version number)
+cpe = "???"
 
+# FIXME: optional but recommended (or remove if irrelevant / not applicable).
+# This is meant to be an URL where people can financially support this app, especially when its development is based
+# on volunteers and/or financed by its community. YunoHost may later advertise it in the webadmin.
+fund = "???"
 
 [integration]
 yunohost = ">= 12.0.9"
 helpers_version = "2.1"
+# FIXME: can be replaced by a list of supported archs using the dpkg --print-architecture nomenclature (amd64/i386/armhf/arm64), for example: ["amd64", "i386"]
 architectures = "all"
 multi_instance = true
 
-#try whether integration is possible later on
+# FIXME: replace with true, false, or "not_relevant".
-ldap = "false"
+# Not to confuse with the "sso" key: the "ldap" key corresponds to wether or not a user *can* login on the app using
-sso = "false"
+# its YunoHost credentials.
+ldap = "?"
 
-disk = "100M"
+# FIXME: replace with true, false, or "not_relevant".
-ram.build = "150M"
+# Not to confuse with the "ldap" key: the "sso" key corresponds to wether or not a user is *automatically logged-in*
-ram.runtime = "100M"
+# on the app when logged-in on the YunoHost portal.
+sso = "?"
+
+# FIXME: replace with an **estimate** minimum disk and RAM requirements. e.g. 20M, 400M, 1G...
+disk = "50M"
+ram.build = "50M"
+ram.runtime = "50M"
 
 [install]
     [install.domain]
+    # this is a generic question - ask strings are automatically handled by YunoHost's core
     type = "domain"
 
-    # unable to get this to work, disable for now    
+    [install.path]
-    #[install.path]
+    # this is a generic question - ask strings are automatically handled by YunoHost's core
-    #type = "path"
+    type = "path"
-    #default = "/idlers"
+    default = "/example"
 
     [install.init_main_permission]
+    # this is a generic question - ask strings are automatically handled by YunoHost's core
+    # This won't be saved as setting and will instead be used to initialize the SSOwat permission
     type = "group"
-    default = "all_users"
+    default = "visitors"
-    [install.user]
+
-    help.en = "The name of the user"
+    [install.language]
-    type = "string"
+    ask.en = "Choose the application language"
-    [install.email]
+    ask.fr = "Choisissez la langue de l'application"
-    help.en = "The email address used for logging in to the application"
+    type = "select"
-    type = "email"
+    choices = ["fr", "en"]
+    default = "fr"
+
+    [install.admin]
+    # this is a generic question - ask strings are automatically handled by YunoHost's core
+    type = "user"
+
     [install.password]
+    # this is a generic question - ask strings are automatically handled by YunoHost's core
+    # Note that user-provided passwords questions are not automatically saved as setting
     help.en = "Use the help field to add an information for the admin about this question."
     help.fr = "Utilisez le champ aide pour ajouter une information à l'intention de l'administrateur à propos de cette question."
     type = "password"
 
 [resources]
+    # See the packaging documentation for the full set
+    # of explanation regarding the behavior and properties for each of those
+
     [resources.sources]
 
     [resources.sources.main]
-    # This will pre-fetch the asset 
+    # This will pre-fetch the asset which can then be deployed during the install/upgrade scripts with :
-    url = "https://github.com/cp6/my-idlers/archive/refs/tags/3.0.zip"
+    #    ynh_setup_source --dest_dir="$install_dir"
-    sha256 = "f92a6dc9c98ec1e3837939db571833d28e72b992f5a9611925e9d242fcb40f72"
+    # You can also define other assets than "main" and add --source_id="foobar" in the previous command
+    url = "https://github.com/foo/bar/archive/refs/tags/v1.2.3.tar.gz"
+    sha256 = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+
+    # These infos are used by https://github.com/YunoHost/apps/blob/master/tools/autoupdate_app_sources/autoupdate_app_sources.py
+    # to auto-update the previous asset urls and sha256sum + manifest version
+    # assuming the upstream's code repo is on github and relies on tags or releases
+    # See the 'sources' resource documentation for more details
+
+    # autoupdate.strategy = "latest_github_tag"
 
     [resources.system_user]
-    user = "__APP_NAME__:rwx"
+    # This will provision/deprovision a unix system user
 
     [resources.install_dir]
-    group = "www-data:r-x"
+    # This will create/remove the install dir as /var/www/$app
+    # and store the corresponding setting $install_dir
+
+    [resources.data_dir]
+    # This will create/remove the data dir as /home/yunohost.app/$app
+    # and store the corresponding setting $data_dir
 
     [resources.permissions]
+    # This will configure SSOwat permission for $domain/$path/
+    # The initial allowed group of user is configured via the init_main_permission question (public=visitors, private=all_users)
     main.url = "/"
 
     [resources.ports]
+    # This will pick a random port for reverse-proxying and store it as the $port setting
 
     [resources.apt]
-    packages = "php8.3, php8.3-cli, php8.3-mbstring, php8.3-xml, php8.3-mysql, php8.3-intl, php8.3-pdo, php8.3-intl, composer, mariadb-server, mariadb-client, php8.3-curl"
+    # This will automatically install/uninstall the following apt packages
+    # and implicitly define the $phpversion setting as 8.0 (if phpX.Y-foobar dependencies are listed)
+    packages = "mariadb-server, deb1, deb2, php8.3-foo, php8.3-bar"
 
     [resources.database]
+    # This will automatically provision/deprovison a MySQL DB and store the corresponding credentials in settings $db_user, $db_name, $db_pwd
     type = "mysql"

scripts/_common.sh

@@ -3,7 +3,3 @@
 #=================================================
 # COMMON VARIABLES AND CUSTOM HELPERS
 #=================================================
-composer_version="2.5.5"
-php_version="8.3"
-# will not stay stable over installs, should not be a problem
-token=$(tr -dc A-Za-z0-9 </dev/urandom | head -c 60)

scripts/backup

@@ -10,23 +10,67 @@ source /usr/share/yunohost/helpers
 
 ynh_print_info "Declaring files to be backed up..."
 
+### N.B. : the following 'ynh_backup' calls are only a *declaration* of what needs
+### to be backuped and not an actual copy of any file. The actual backup that
+### creates and fills the archive with the files happens in the core after this
+### script is called. Hence ynh_backups calls take basically 0 seconds to run.
+
 #=================================================
 # BACKUP THE APP MAIN DIR
 #=================================================
 
 ynh_backup "$install_dir"
 
+#=================================================
+# BACKUP THE DATA DIR
+#=================================================
+
+# Only relevant if there is a "data_dir" resource for this app
+# NB: $data_dir is not backuped during safety-backup-before-upgrades,
+# because the data dir may be huge and we don't want to just yolo-create a 10+ GB archive just for upgrades.
+# On the other hand, $data_dir is also *not* removed by default in the "app remove" step unless --purge is used
+# This means that even if the upgrade fails and the backup is restored, the data are still there.
+ynh_backup "$data_dir"
+
 #=================================================
 # BACKUP SYSTEM CONFIGURATION
 #=================================================
 
+# Backup the PHP-FPM configuration
+ynh_backup "/etc/php/$php_version/fpm/pool.d/$app.conf"
+
+# Backup the NGINX configuration
 ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf"
 
+# Backup the systemd service unit
+ynh_backup "/etc/systemd/system/$app.service"
+
+# Backup the logrotate configuration
+ynh_backup "/etc/logrotate.d/$app"
+
+# Backup the Fail2Ban config
+ynh_backup "/etc/fail2ban/jail.d/$app.conf"
+ynh_backup "/etc/fail2ban/filter.d/$app.conf"
+
+#=================================================
+# BACKUP VARIOUS FILES
+#=================================================
+
+ynh_backup "/etc/cron.d/$app"
+
+ynh_backup "/etc/$app/"
+
+# NB: /var/log is not backuped during safety-backup-before-upgrades, same as $data_dir
+ynh_backup "/var/log/$app/"
+
 #=================================================
 # BACKUP THE MYSQL DATABASE
 #=================================================
 ynh_print_info "Backing up the MySQL database..."
 
+### (However, things like MySQL dumps *do* take some time to run, though the
+### copy of the generated dump to the archive still happens later)
+
 ynh_mysql_dump_db > db.sql
 
 #=================================================

scripts/change_url

@@ -1,5 +1,6 @@
 #!/bin/bash
 
+## this script is only run if actual change to domain/path is detected, if you're here either $domain or $path changed
 ## new location is available via $domain and $path (or $new_domain and $new_path variables if you want to be explicit)
 ## old values are available via, you guessed it, $old_domain and $old_path
 
@@ -13,8 +14,9 @@ source /usr/share/yunohost/helpers
 #=================================================
 # STOP SYSTEMD SERVICE
 #=================================================
+ynh_script_progression "Stopping $app's systemd service..."
 
-## My Idlers runs as a Laravel app on nginx; keep nginx running, so no stop
+ynh_systemctl --service="$app" --action="stop"
 
 #=================================================
 # MODIFY URL IN NGINX CONF
@@ -28,14 +30,14 @@ ynh_config_change_url_nginx
 # SPECIFIC MODIFICATIONS
 #=================================================
 
-## Only the app_url in .env needs to change
+## do any changes to files that reference specific installation domain/path, i.e. regenerate configs etc
-sed -i -e 's/$old_domain/new_domain/g' $install_dir/.env
-sed -i -e 's/$old_path/new_path/g' $install_dir/.env
 
-## perhaps a better option than sed: ynh_replace + ynh_store_file_checksum; try it out later
+#=================================================
-# ynh_replace --match=$old_domain --replace="$new_domain --file="$install_dir/.env"
+# START SYSTEMD SERVICE
-# ynh_replace --match=$old_path --replace="$new_path --file="$install_dir/.env"
+#=================================================
-ynh_store_file_checksum "$install_dir/.env"
+ynh_script_progression "Starting $app's systemd service..."
+
+ynh_systemctl --service="$app" --action="start"
 
 #=================================================
 # END OF SCRIPT

scripts/config

@@ -0,0 +1,96 @@
+#!/bin/bash
+# In simple cases, you don't need a config script.
+
+# With a simple config_panel.toml, you can write in the app settings, in the
+# upstream config file or replace complete files (logo ...) and restart services.
+
+# The config scripts allows you to go further, to handle specific cases
+# (validation of several interdependent fields, specific getter/setter for a value,
+# display dynamic informations or choices, pre-loading of config type .cube... ).
+
+#=================================================
+# IMPORT GENERIC HELPERS
+#=================================================
+
+source /usr/share/yunohost/helpers
+
+ynh_abort_if_errors
+
+#=================================================
+# RETRIEVE ARGUMENTS
+#=================================================
+
+install_dir=$(ynh_app_setting_get --key=install_dir)
+
+#=================================================
+# SPECIFIC GETTERS FOR TOML SHORT KEY
+#=================================================
+
+get__amount() {
+    # Here we can imagine to have an API call to stripe to know the amount of donation during a month
+    local amount=200
+
+    # It's possible to change some properties of the question by overriding it:
+    if [ "$amount" -gt 100 ]; then
+    cat << EOF
+style: success
+value: $amount
+ask:
+  en: A lot of donation this month: **$amount €**
+EOF
+    else
+    cat << EOF
+style: danger
+value: $amount
+ask:
+  en: Not so much donation this month: $amount €
+EOF
+    fi
+}
+
+get__prices() {
+    local prices
+    prices="$(grep "DONATION\['" "$install_dir/settings.py" | sed -r "s@^DONATION\['([^']*)'\]\['([^']*)'\] = '([^']*)'@\1/\2/\3@g" | sed -z 's/\n/,/g;s/,$/\n/')"
+    if [ "$prices" == "," ]; then
+        # Return YNH_NULL if you prefer to not return a value at all.
+        echo YNH_NULL
+    else
+        echo "$prices"
+    fi
+}
+
+#=================================================
+# SPECIFIC VALIDATORS FOR TOML SHORT KEYS
+#=================================================
+validate__publishable_key() {
+
+    # We can imagine here we test if the key is really a publishable key
+    (is_secret_key "$publishable_key") &&
+        echo 'This key seems to be a secret key'
+}
+
+#=================================================
+# SPECIFIC SETTERS FOR TOML SHORT KEYS
+#=================================================
+set__prices() {
+
+    #---------------------------------------------
+    # IMPORTANT: setters are triggered only if a change is detected
+    #---------------------------------------------
+    for price in $(echo "$prices" | sed "s/,/ /"); do
+        frequency=$(echo "$price" | cut -d/ -f1)
+        currency=$(echo "$price" | cut -d/ -f2)
+        price_id=$(echo "$price" | cut -d/ -f3)
+        sed "d/DONATION\['$frequency'\]\['$currency'\]" "$install_dir/settings.py"
+
+        echo "DONATION['$frequency']['$currency'] = '$price_id'" >> "$install_dir/settings.py"
+    done
+
+    #---------------------------------------------
+    # IMPORTANT: to be able to upgrade properly, you have to save the value in settings too
+    #---------------------------------------------
+    ynh_app_setting_set --key=prices --value="$prices"
+}
+
+#=================================================
+ynh_app_config_run "$1"

scripts/install

@@ -7,12 +7,52 @@
 source _common.sh
 source /usr/share/yunohost/helpers
 
+### Install parameters are automatically saved as settings
+###
+### Settings are automatically loaded as bash variables
+### in every app script context, therefore typically these will exist:
+### - $domain
+### - $path
+### - $language
+### ... etc
+###
+### Resources defined in the manifest are provisioned prior to this script
+### and corresponding settings are also available, such as:
+### - $install_dir
+### - $port
+### - $db_name
+### ...
+###
+### $app is the app id (i.e. 'example' for first install,
+### or 'example__2', '__3'... for multi-instance installs)
+
+#=================================================
+# INITIALIZE AND STORE SETTINGS
+#=================================================
+
+# If you need to, you can define custom settings
+# (or remove this section entirely if not relevant for you)
+foo="bar"
+ynh_app_setting_set --key=foo --value=$foo
+
+ynh_app_setting_set --key=php_upload_max_filesize --value=50M
+ynh_app_setting_set --key=php_post_max_size --value=50M
+
 #=================================================
 # DOWNLOAD, CHECK AND UNPACK SOURCE
 #=================================================
 ynh_script_progression "Setting up source files..."
 
+### `ynh_setup_source` is used to install an app from a zip or tar.gz file,
+### downloaded from an upstream source, like a git repository.
+### `ynh_setup_source` use the file manifest.toml
+
+# Download, check integrity, uncompress and patch the source from manifest.toml
 ynh_setup_source --dest_dir="$install_dir"
+
+### $install_dir will automatically be initialized with some decent
+### permission by default... however, you may need to recursively reapply
+### ownership to all files such as after the ynh_setup_source step
 chown -R "$app:www-data" "$install_dir"
 
 #=================================================
@@ -20,58 +60,140 @@ chown -R "$app:www-data" "$install_dir"
 #=================================================
 ynh_script_progression "Adding $app's configuration files..."
 
-ynh_config_add --template=.env --destination="$install_dir/.env"
+### You can add specific configuration files.
+###
+### Typically, put your template conf file in ../conf/your_config_file
+### The template may contain strings such as __FOO__ or __FOO_BAR__,
+### which will automatically be replaced by the values of $foo and $foo_bar
+###
+### ynh_config_add will also keep track of the config file's checksum,
+### which later during upgrade may allow to automatically backup the config file
+### if it's found that the file was manually modified
+###
+### Check the documentation of `ynh_config_add` for more info.
 
-chmod 640 "$install_dir/.env"
+ynh_config_add --template="some_config_file" --destination="$install_dir/some_config_file"
-chown "$app:www-data" "$install_dir/.env"
+
+# FIXME: this should be handled by the core in the future
+### You may need to use chmod 600 instead of 400,
+### for example if the app is expected to be able to modify its own config
+chmod 400 "$install_dir/some_config_file"
+chown "$app:$app" "$install_dir/some_config_file"
+
+### For more complex cases where you want to replace stuff using regexes,
+### you shoud rely on ynh_replace (which is basically a wrapper for sed)
+### When doing so, you also need to manually call ynh_store_file_checksum
+###
+### ynh_replace --match="match_string" --replace="replace_string" --file="$install_dir/some_config_file"
+### ynh_store_file_checksum "$install_dir/some_config_file"
 
 #=================================================
 # SYSTEM CONFIGURATION
 #=================================================
 ynh_script_progression "Adding system configurations related to $app..."
 
+### `ynh_config_add_phpfpm` is used to set up a PHP config.
+### You can remove it if your app doesn't use PHP.
+### `ynh_config_add_phpfpm` will use the files conf/extra_php-fpm.conf
+### If you're not using these lines:
+###   - You can remove these files in conf/.
+###   - Remove the section "BACKUP THE PHP-FPM CONFIGURATION" in the backup script
+###   - Remove also the section "REMOVE PHP-FPM CONFIGURATION" in the remove script
+###   - As well as the section "RESTORE THE PHP-FPM CONFIGURATION" in the restore script
+###     with the reload at the end of the script.
+###   - And the section "PHP-FPM CONFIGURATION" in the upgrade script
+
+# Create a PHP-FPM config (with conf/extra_php-fpm.conf being appended to it)
+ynh_config_add_phpfpm
+
+# Create a dedicated NGINX config using the conf/nginx.conf template
 ynh_config_add_nginx
 
-#=================================================
+### `ynh_config_add_systemd` is used to configure a systemd script for an app.
-# INSTALL APP WITH COMPOSER
+### It can be used for apps that use sysvinit (with adaptation) or systemd.
-#=================================================
+### Have a look at the app to be sure this app needs a systemd script.
-ynh_script_progression "Installing app with Composer..."
+### `ynh_config_add_systemd` will use the file conf/systemd.service
+### If you're not using these lines:
+###   - You can remove those files in conf/.
+###   - Remove the section "BACKUP SYSTEMD" in the backup script
+###   - Remove also the section "STOP AND REMOVE SERVICE" in the remove script
+###   - As well as the section "RESTORE SYSTEMD" in the restore script
+###   - And the section "SETUP SYSTEMD" in the upgrade script
 
-ynh_composer_install
+# Create a dedicated systemd config
-ynh_composer_exec install --no-dev
+ynh_config_add_systemd
 
-#=================================================
+### `yunohost service add` integrates a service in YunoHost. It then gets
-# BUILDING
+### displayed in the admin interface and through the others `yunohost service` commands.
-#=================================================
+### (N.B.: this line only makes sense if the app adds a service to the system!)
-ynh_script_progression "configuring $app..."
+### If you're not using these lines:
+###   - You can remove these files in conf/.
+###   - Remove the section "REMOVE SERVICE INTEGRATION IN YUNOHOST" in the remove script
+###   - As well as the section "INTEGRATE SERVICE IN YUNOHOST" in the restore script
+###   - And the section "INTEGRATE SERVICE IN YUNOHOST" in the upgrade script
 
-pushd "$install_dir"
+### Additional options starting with 3.8:
-	"php$php_version" artisan key:generate -n --force --env
+###
-	"php$php_version" artisan make:database $app
+### --needs_exposed_ports "$port" a list of ports that needs to be publicly exposed
-	"php$php_version" artisan migrate:fresh --seed -n --force
+###                               which will then be checked by YunoHost's diagnosis system
-	"php$php_version" artisan config:clear -n
+###                               (N.B. DO NOT USE THIS if the port is only internal!!!)
-	"php$php_version" artisan config:cache -n
+###
-popd
+### --test_status "some command"  a custom command to check the status of the service
+###                               (only relevant if 'systemctl status' doesn't do a good job)
+###
+### --test_conf "some command"    some command similar to "nginx -t" that validates the conf of the service
+###
+### Re-calling 'yunohost service add' during the upgrade script is the right way
+### to proceed if you later realize that you need to enable some flags that
+### weren't enabled on old installs (be careful it'll override the existing
+### service though so you should re-provide all relevant flags when doing so)
+yunohost service add "$app" --description="A short description of the app" --log="/var/log/$app/$app.log"
 
+### `ynh_config_add_logrotate` is used to configure a logrotate configuration for the logs of this app.
+### Use this helper only if there is effectively a log file for this app.
+### If you're not using this helper:
+###   - Remove the section "BACKUP LOGROTATE" in the backup script
+###   - Remove also the section "REMOVE LOGROTATE CONFIGURATION" in the remove script
+###   - As well as the section "RESTORE THE LOGROTATE CONFIGURATION" in the restore script
+###   - And the section "SETUP LOGROTATE" in the upgrade script
 
-# file was touched by artisan, create a new key (copy/paste from Lychee)
+# Use logrotate to manage application logfile(s)
-ynh_store_file_checksum "$install_dir/.env"
+ynh_config_add_logrotate
-app_key=$(cat $install_dir/.env | grep -e ^APP_KEY | cut -c 9-)
-ynh_app_setting_set --key=app_key --value=$app_key
 
-# group only, make it www-data vs user/group $app:www-data
+# Create a dedicated Fail2Ban config
-chgrp "www-data" -R "$install_dir/storage" "$install_dir/public" 
+ynh_config_add_fail2ban --logpath="/var/log/nginx/${domain}-error.log" --failregex="Regex to match into the log for a failed login"
-chmod -R 2775 "$install_dir/storage" "$install_dir/app" "$install_dir/public" "$install_dir/bootstrap/"
 
 #=================================================
 # SETUP APPLICATION WITH CURL
 #=================================================
-ynh_script_progression "Finalizing installation..."
 
-# Installation with curl: set up the first/single user
+### Use these lines only if the app installation needs to be finalized through
-ynh_local_curl "/INSTALL_PATH" "key1=$user" "key2=$email" "key3=$password" "key4=$password"
+### web forms. We generally don't want to ask the final user,
+### so we're going to use curl to automatically fill the fields and submit the
+### forms.
+
+# Installation with curl
+ynh_script_progression "Finalizing installation..."
+ynh_local_curl "/INSTALL_PATH" "key1=value1" "key2=value2" "key3=value3"
+
+#=================================================
+# START SYSTEMD SERVICE
+#=================================================
+ynh_script_progression "Starting $app's systemd service..."
+
+### `ynh_systemctl` is used to start a systemd service for an app.
+### Only needed if you have configure a systemd service
+### If you're not using these lines:
+###   - Remove the section "STOP SYSTEMD SERVICE" and "START SYSTEMD SERVICE" in the backup script
+###   - As well as the section "START SYSTEMD SERVICE" in the restore script
+###   - As well as the section"STOP SYSTEMD SERVICE" and "START SYSTEMD SERVICE" in the upgrade script
+###   - And the section "STOP SYSTEMD SERVICE" and "START SYSTEMD SERVICE" in the change_url script
+
+# Start a systemd service
+ynh_systemctl --service="$app" --action="start"
 
 #=================================================
 # END OF SCRIPT
 #=================================================
+
 ynh_script_progression "Installation of $app completed"

scripts/remove

@@ -7,6 +7,19 @@
 source _common.sh
 source /usr/share/yunohost/helpers
 
+### Settings are automatically loaded as bash variables
+### in every app script context, therefore typically these will exist:
+### - $domain
+### - $path
+### - $language
+### - $install_dir
+### - $port
+### ...
+
+### For remove operations:
+### - the core will deprovision every resource defined in the manifest **after** this script is ran
+### this includes removing the install directory, and data directory (if --purge was used)
+
 #=================================================
 # REMOVE SYSTEM CONFIGURATIONS
 #=================================================
@@ -14,8 +27,26 @@ ynh_script_progression "Removing system configurations related to $app..."
 
 ### This should be a symetric version of what happens in the install script
 
+ynh_config_remove_fail2ban
+
+ynh_config_remove_logrotate
+
+# Remove the service from the list of services known by YunoHost (added from `yunohost service add`)
+if ynh_hide_warnings yunohost service status "$app" >/dev/null; then
+    yunohost service remove "$app"
+fi
+ynh_config_remove_systemd
+
 ynh_config_remove_nginx
 
+ynh_config_remove_phpfpm
+
+# Remove other various files specific to the app... such as:
+
+ynh_safe_rm "/etc/cron.d/$app"
+
+ynh_safe_rm "/etc/$app"
+
 #=================================================
 # END OF SCRIPT
 #=================================================

scripts/restore

@@ -15,8 +15,21 @@ ynh_script_progression "Restoring the app main directory..."
 
 ynh_restore "$install_dir"
 
+### $install_dir will automatically be initialized with some decent
+### permissions by default... however, you may need to recursively reapply
+### ownership to all files such as after the ynh_setup_source step
 chown -R "$app:www-data" "$install_dir"
 
+#=================================================
+# RESTORE THE DATA DIRECTORY
+#=================================================
+ynh_script_progression "Restoring the data directory..."
+
+ynh_restore "$data_dir"
+
+### (Same as for install dir)
+chown -R "$app:www-data" "$data_dir"
+
 #=================================================
 # RESTORE THE MYSQL DATABASE
 #=================================================
@@ -29,13 +42,47 @@ ynh_mysql_db_shell < ./db.sql
 #=================================================
 ynh_script_progression "Restoring system configurations related to $app..."
 
+### This should be a symetric version of what happens in the install script
+
+ynh_restore "/etc/php/$php_version/fpm/pool.d/$app.conf"
+
 ynh_restore "/etc/nginx/conf.d/$domain.d/$app.conf"
 
+ynh_restore "/etc/systemd/system/$app.service"
+systemctl enable "$app.service" --quiet
+
+yunohost service add "$app" --description="A short description of the app" --log="/var/log/$app/$app.log"
+
+ynh_restore "/etc/logrotate.d/$app"
+
+ynh_restore "/etc/fail2ban/jail.d/$app.conf"
+ynh_restore "/etc/fail2ban/filter.d/$app.conf"
+ynh_systemctl --action=restart --service=fail2ban
+
+#=================================================
+# RESTORE VARIOUS FILES
+#=================================================
+
+ynh_restore "/etc/cron.d/$app"
+ynh_restore "/etc/$app/"
+
+### For apps with huge logs, you might want to not backup logs every time:
+### The mkdir call is just here in case the log directory was not backed up.
+### mkdir -p "/var/log/$app"
+### chown $app:www-data "/var/log/$app"
+### ynh_restore "/var/log/$app/" || true
+###
+### For other apps, the simple way is better:
+ynh_restore "/var/log/$app/"
+
 #=================================================
 # RELOAD NGINX AND PHP-FPM OR THE APP SERVICE
 #=================================================
 ynh_script_progression "Reloading NGINX web server and $app's service..."
 
+### Typically you only have either $app or PHP-FPM but not both at the same time...
+ynh_systemctl --service="$app" --action="start"
+
 ynh_systemctl --service="php$php_version-fpm" --action=reload
 
 ynh_systemctl --service=nginx --action=reload

scripts/upgrade

@@ -63,13 +63,6 @@ ynh_setup_source --dest_dir="$install_dir" --full_replace --keep=".env data"
 ### ownership to all files such as after the ynh_setup_source step
 chown -R "$app:www-data" "$install_dir"
 
-#=================================================
-# TODO - DB migration if applicable
-#=================================================
-ynh_script_progression "Migrating $app's database to the new data model..."
-
-## find upstream migration script
-
 #=================================================
 # UPDATE A CONFIG FILE
 #=================================================
@@ -80,14 +73,13 @@ ynh_script_progression "Updating $app's configuration files..."
 ### The file will automatically be backed-up if it's found to be manually modified (because
 ### ynh_config_add keeps track of the file's checksum)
 
-#ynh_config_add --template="some_config_file" --destination="$install_dir/some_config_file"
+ynh_config_add --template="some_config_file" --destination="$install_dir/some_config_file"
-# there's just the nginx conf and the .env that's still available (--keep above)
 
 # FIXME: this should be handled by the core in the future
 ### You may need to use chmod 600 instead of 400,
 ### for example if the app is expected to be able to modify its own config
-#chmod 400 "$install_dir/some_config_file"
+chmod 400 "$install_dir/some_config_file"
-#chown "$app:$app" "$install_dir/some_config_file"
+chown "$app:$app" "$install_dir/some_config_file"
 
 ### For more complex cases where you want to replace stuff using regexes,
 ### you shoud rely on ynh_replace (which is basically a wrapper for sed)
@@ -103,9 +95,24 @@ ynh_script_progression "Upgrading system configurations related to $app..."
 
 ### This should be a literal copypaste of what happened in the install's "System configuration" section
 
+ynh_config_add_phpfpm
+
 ynh_config_add_nginx
 
-#ynh_config_add_fail2ban --logpath="/var/log/nginx/${domain}-error.log" --failregex="Regex to match into the log for a failed login"
+ynh_config_add_systemd
+
+yunohost service add "$app" --description="A short description of the app" --log="/var/log/$app/$app.log"
+
+ynh_config_add_logrotate
+
+ynh_config_add_fail2ban --logpath="/var/log/nginx/${domain}-error.log" --failregex="Regex to match into the log for a failed login"
+
+#=================================================
+# START SYSTEMD SERVICE
+#=================================================
+ynh_script_progression "Starting $app's systemd service..."
+
+ynh_systemctl --service="$app" --action="start"
 
 #=================================================
 # END OF SCRIPT