Merge branch 'feature/docs-user-data' into 'main'

Add documentation for the user-data modules

See merge request alpine/cloud/tiny-cloud!135

user-data-file.md

@@ -0,0 +1,93 @@
+# User Data
+
+User-data file is loaded during early stage. Location of this file defined by kernel paramter: `ds=<provider>;s=<path>`. For example for nocloud provider: `ds=nocloud;s=http://my.miniserve.instance/tinycloud/` tiny cloud will search for a file with name "user-data" at http://my.miniserve.instance/tinycloud/ resource.
+
+Tiny-Cloud currently supports several user-data types and you could use ONE of them:
+
+- alpine-config
+- cloud-config
+- script
+
+The `user-data` file is used to configure Alpine Linux state at the boot time. It supports a variety of modules that can be used to install packages, configure users and groups, and more.
+
+## Alpine-Config Data Type
+
+Alpine config Must have `#alpine-config` as fist line in the file.
+Rest of the file is a yaml which describes several alpine-spesific configuration paramters:
+
+```yaml
+#alpine-config
+apk:
+  cache: # path to apk cache where /etc/apk/cache link follows
+  repositories: # <map> defines resulted url https://dl-cdn.alpinelinux.org/alpine/edge/community
+    - base_url: # The base usr of the repository ( https://dl-cdn.alpinelinux.org/alpine )
+      version: # (optional) examples: [ 3.16 | 3.21 | edge ]  if not set will be retrieved from the system
+      repos: # <list>
+        - community
+
+autoinstall: # [ true | false] install alpine on the biggest empty disk found in the system
+```
+
+## Cloud-Config Data Type
+
+Alpine config Must have `#cloud-config` as fist line in the file.
+
+```yaml
+#cloud-config
+user: # <map> sets default user
+  name: # <string>
+
+groups: # <list> groups for default user
+  - wheel
+  - admin
+
+users: # <list>
+  # first one become default user
+  - name:
+    homedir:
+    shell:
+    primary_group:
+    gecos: # description for the user
+    system: # [ true | false ] create a system user
+    no_create_home: # [ true | false ] do not create home directory for the user. Default: false
+    lock_passwd: # reset password of the user
+    ssh_authorized_keys: # <list>
+    groups: wheel,power # comma-separated list of groups for the user
+    doas: # content of the /etc/doas.d/<name>.conf doas file
+      -
+
+ssh_authorized_keys: # public key to be authorized as default user
+
+write_files: # <list> Writes content of the file to the system. Can be used to define configuration files.
+  - path: # destination path of the file (required)
+    permissions: # file mode (default 0644)
+    owner: # owner:group of the file (default root:root)
+    encoding: # provided endoding of the file [gzip|gz|gz+base64|gzip+base64|gz+b64|gzip+b64|base64|b64|text/plain] (default text/plain)
+    append: # if "true", then content will be added to the end of the file
+    content: | # (required)
+      here is multiline
+      content of your file
+
+ntp:
+  enabled: # checks for [ yes | true ]. Otherwise do not enables ntp service
+  ntp_client: # [ ntpd | chrony | openntpd ] (default: chrony)
+
+package_update: # if "true" runs `apk update`
+
+package_upgrade: # if "true" runs `apk upgrade`
+
+packages: # <list>
+  - curl
+  - bash
+```
+
+## Script Data Type
+
+Scipt user-data could be used to run arbitrary user script at the system init. User-data file must have script executor specific shebang, started with `#!`
+For example shell script:
+
+```shell
+#!/bin/sh
+
+echo "running custom script at init time"
+```