24 files changed, 252 insertions, 0 deletions
diff --git a/.ddev/nginx/extra.conf b/.ddev/nginx/extra.conf
new file mode 100644
index 0000000..a1a3339
--- /dev/null
+++ b/.ddev/nginx/extra.conf
@@ -0,0 +1,11 @@
+# Direct /doc to generated api docs
+location ^~ /doc {
+	alias /var/www/html/core/doc/html;
+	index index.html;
+}
+
+# Direct /coverage to code coverage report
+location ^~ /coverage {
+	alias /var/www/html/core/tests/results/coverage;
+	index index.html;
+}
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..7585238
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1 @@
+book
diff --git a/doc/book.toml b/doc/book.toml
new file mode 100644
index 0000000..71ccc51
--- /dev/null
+++ b/doc/book.toml
@@ -0,0 +1,6 @@
+[book]
+authors = ["Harald Eilertsen"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Hubzilla DDEV Environment"
diff --git a/doc/src/README.md b/doc/src/README.md
new file mode 100644
index 0000000..c776b3a
--- /dev/null
+++ b/doc/src/README.md
@@ -0,0 +1,14 @@
+# Introduction
+
+[DDEV] is a wrapper for docker-compose (or podman) that makes it easy to set up an isolated development environment for web applications.
+
+This repository contains the configuration, and some helper scripts to help you set up a local Hubzilla development server with minimal manual intervention.
+
+You don't need to know the details of DDEV to be able to use the Hubzilla DDEV environment, but in case you want to know the details you can always consult the [DDEV Documentation] at any time.
+
+
+
+[DDEV]: https://ddev.com
+[DDEV Documentation]: https://ddev.readthedocs.io
+[DDEV installation instructions]: https://ddev.readthedocs.io/en/stable/
+[hubzilla-ddev repository]: https://code.volse.net/hubzilla/hubzilla-ddev.git/
diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md
new file mode 100644
index 0000000..6d4f012
--- /dev/null
+++ b/doc/src/SUMMARY.md
@@ -0,0 +1,26 @@
+# Summary
+
+[Introduction](README.md)
+
+# Getting started
+
+- [Requirements](./requirements.md)
+- [Setup](./setup.md)
+- [Using a different domain](./configure-domain.md)
+- [Installing Hubzilla](./installation/README.md)
+  - [Database setup](./installation/db-setup.md)
+  - [Creating the admin user](./installation/creating-admin.md)
+  - [Safety notes](./installation/safety.md)
+
+# Usage
+
+- [Daily usage](./usage/README.md)
+  - [Useful commands](./usage/ddev-commands.md)
+    - [ddev status](./usage/ddev-status.md)
+	- [ddev stop](./usage/ddev-stop.md)
+	- [ddev start](./usage/ddev-start.md)
+	- [ddev restart](./usage/ddev-restart.md)
+	- [ddev delete](./usage/ddev-delete.md)
+    - [ddev composer](./usage/ddev-composer.md)
+	- [ddev phpunit](./usage/ddev-phpunit.md)
+  - [Testing](./usage/testing/README.md)
diff --git a/doc/src/chapter_1.md b/doc/src/chapter_1.md
new file mode 100644
index 0000000..b743fda
--- /dev/null
+++ b/doc/src/chapter_1.md
@@ -0,0 +1 @@
+# Chapter 1
diff --git a/doc/src/configure-domain.md b/doc/src/configure-domain.md
new file mode 100644
index 0000000..efded62
--- /dev/null
+++ b/doc/src/configure-domain.md
@@ -0,0 +1,9 @@
+# Using a different domain
+
+By default DDEV will create a local site using the directory where the DDEV configuration folder is located with `.ddev.site` appended.
+
+If you want to use a different name, you can do so byssuing the command `ddev config --project-name=<name>`, or by setting the `name` property in `.ddev/config.yaml`.
+
+See the [DDEV documentation] for further into.
+
+[DDEV documentation]: https://ddev.readthedocs.io/en/stable/users/configuration/config/#name
diff --git a/doc/src/https:/ddev.com b/doc/src/https:/ddev.com
new file mode 100644
index 0000000..28fed35
--- /dev/null
+++ b/doc/src/https:/ddev.com
@@ -0,0 +1 @@
+# DDEV
diff --git a/doc/src/installation/README.md b/doc/src/installation/README.md
new file mode 100644
index 0000000..3ccd2f9
--- /dev/null
+++ b/doc/src/installation/README.md
@@ -0,0 +1,3 @@
+# Installing Hubzilla
+
+Once the Hubzilla DDEV environment is up and running, you can set up Hubzilla as usual using the Hubzilla Web UI.
diff --git a/doc/src/installation/creating-admin.md b/doc/src/installation/creating-admin.md
new file mode 100644
index 0000000..72fa933
--- /dev/null
+++ b/doc/src/installation/creating-admin.md
@@ -0,0 +1,7 @@
+# Creating the admin user
+
+When it comes to creating the admin user, you can type in any email address in the email field. Outgoing emails are caught by the builtin Mailpit service, and you can access them by visiting `https://hubzilla-ddev.ddev.site:8026`[^note] (or by typing `ddev mailpit` in the terminal.)
+
+Use that to get the registration token you need to register the first user.
+
+[^note]: Adapt as necessary for your setup.
diff --git a/doc/src/installation/db-setup.md b/doc/src/installation/db-setup.md
new file mode 100644
index 0000000..853146a
--- /dev/null
+++ b/doc/src/installation/db-setup.md
@@ -0,0 +1,21 @@
+# Database setup
+
+By default the dev environment is set up with a Postgres database running on the host reachable as `db` from within the docker container where the code is running. In the setup screen, set the type to "PostgreSQL", leave the "Port" as 0, and set all the other fields to `db`,
+
+The generated `.htconfig.php` file should contain the following after you're done:
+
+```
+$db_host = 'db';
+$db_port = '0';
+$db_user = 'db';
+$db_pass = 'db';
+$db_data = 'db';
+$db_type = '1'; // an integer. 0 or unset for mysql, 1 for postgres
+```
+
+If you prefer to use MySQL or Mariadb as the database backend instead, you can change this by issuing the command:
+```
+% ddev config --database=mariadb:10.11
+```
+
+And then restart the environment by running `ddev restart`.
diff --git a/doc/src/installation/safety.md b/doc/src/installation/safety.md
new file mode 100644
index 0000000..2fed69d
--- /dev/null
+++ b/doc/src/installation/safety.md
@@ -0,0 +1,10 @@
+# Safety notes
+
+Be aware that this hub will run in an isolated network on your local machine, and while it will be able to reach out to other sites on the internet, it is _not reachable_ from the outside.
+
+In other words: _don't try to connect to other users on real hubs or fediverse instances!_
+
+You may want modify the directory mode line in your generated `.htconfig.php` like this to be on the safe side:
+```
+App::$config['system']['directory_mode']  = DIRECTORY_MODE_STANDALONE;
+```
diff --git a/doc/src/requirements.md b/doc/src/requirements.md
new file mode 100644
index 0000000..5754efb
--- /dev/null
+++ b/doc/src/requirements.md
@@ -0,0 +1,7 @@
+# Requirements
+
+Docker and DDEV must both be installed and working on your system before you try to start the Hubzilla DDEV environment.
+
+See the [DDEV installation instructions] for the details.
+
+[DDEV installation instructions]: https://ddev.readthedocs.io/en/stable/
diff --git a/doc/src/setup.md b/doc/src/setup.md
new file mode 100644
index 0000000..99e029c
--- /dev/null
+++ b/doc/src/setup.md
@@ -0,0 +1,28 @@
+# Setup
+
+Clone the [hubzilla-ddev repository]:
+```
+% git clone https://code.volse.net/hubzilla/hubzilla-ddev.git
+```
+
+Now clone the Hubzilla core repository into the `core` subdirectory:
+```
+% cd hubzilla-ddev && git clone https://framagit.org/hubzilla/core.git
+```
+
+Then set up the hubzilla installation as usual:
+```
+% cd core
+% mkdir -m 775 -p store/\[data\]/smarty3
+% ./util/add_addon_repo https://framagit.org/hubzilla/addons.git hzaddons
+```
+
+You should now be ready to start the server:
+```
+% ddev start
+```
+
+This will generate and download the required docker containers, and start all the services. Once it's started you should be able to access the instance at `https://hubzilla-ddev.ddev.site`[^note] to finish the installation and create the administrator account and channel.
+
+[hubzilla-ddev repository]: https://code.volse.net/hubzilla/hubzilla-ddev.git/
+[^note]: If you cloned the repo to another directory than `hubzilla-ddev`, the URL for the site will be the name of your directory followed by `.ddev.site`.
diff --git a/doc/src/usage/README.md b/doc/src/usage/README.md
new file mode 100644
index 0000000..3e29683
--- /dev/null
+++ b/doc/src/usage/README.md
@@ -0,0 +1,8 @@
+# Usage
+
+Once the ddev environment is started, you can interact with the hub as normal.
+
+Any changes you do to the source files under the `core` directory, should be
+immediately active in the environment. This makes it really convenient to work
+on everything from translations, documentation, and even code changes,
+features, new addons etc.
diff --git a/doc/src/usage/ddev-commands.md b/doc/src/usage/ddev-commands.md
new file mode 100644
index 0000000..e293308
--- /dev/null
+++ b/doc/src/usage/ddev-commands.md
@@ -0,0 +1,7 @@
+# Useful DDEV commands
+
+DDEV provides out of the box a few convenient commands that can help with some common tasks. In addition we have added a few commands of our own that will be useful when working on Hubzilla.
+
+We will only document the most common of the built in commands in this guide, but see the [DDEV documentation] for the full list.
+
+[DDEV documentation]: https://ddev.readthedocs.io/en/stable/users/usage/commands/
diff --git a/doc/src/usage/ddev-composer.md b/doc/src/usage/ddev-composer.md
new file mode 100644
index 0000000..d99ddea
--- /dev/null
+++ b/doc/src/usage/ddev-composer.md
@@ -0,0 +1,14 @@
+# ddev composer
+
+This command works just like the regular composer command, except it runs in the web container.
+
+**Example:** Install all the dependencies of the project in the web container.
+
+```bash
+$ ddev composer install
+```
+
+
+It is recommended to always run composer via ddev, as this ensures that the
+dependencies installed works with the version of PHP that is being used by the
+container. This may be different from what is installed on the host system.
diff --git a/doc/src/usage/ddev-delete.md b/doc/src/usage/ddev-delete.md
new file mode 100644
index 0000000..678e8da
--- /dev/null
+++ b/doc/src/usage/ddev-delete.md
@@ -0,0 +1,14 @@
+# ddev delere
+
+Delete the environment and the containers completely.
+
+Any changes you have made to the file system is kept, but the database etc is destroyed.
+
+The `--omit-snapshots` argument, if specified, tells DDEV to _not_ keep a dump of
+the database content for later. If you want it to dump the database so you can
+load it back at a later time, don't use this argument.
+
+**Example:**
+```bash
+$ ddev delete --omit-snapshot
+```
diff --git a/doc/src/usage/ddev-phpunit.md b/doc/src/usage/ddev-phpunit.md
new file mode 100644
index 0000000..40b9fcc
--- /dev/null
+++ b/doc/src/usage/ddev-phpunit.md
@@ -0,0 +1,27 @@
+# ddev phpunit
+
+Runs the unit tests in the web container.
+
+**Example:** Run the unit tests:
+```bash
+$ ddev phpunit
+```
+
+Any additional args[^note] will be passed to the PHPUnit executable in the container:
+
+**Example:** Run only tests with names mathcing "Access":
+```bash
+$ ddev phpunit --filter Access
+```
+
+The command has several special subcommand for common tasks:
+
+- `ddev phpunit coverage` to generate coverage reports.
+- `ddev phpunit debug` to enable step debugging.
+- `ddev phpunit provile` to generate profiling info.
+
+These subcommands will be further described elsewhere.
+
+This command is provided by the Hubzilla DDEV environment.
+
+[^note]:Except the special commands as noted below.
diff --git a/doc/src/usage/ddev-restart.md b/doc/src/usage/ddev-restart.md
new file mode 100644
index 0000000..57d570b
--- /dev/null
+++ b/doc/src/usage/ddev-restart.md
@@ -0,0 +1,9 @@
+# ddev restart
+
+Restart the environment. Just the same as running `ddev stop` immediately followed by `ddev start`.
+This can be useful if you have made changes the DDEV configuration etc.
+
+**Example:**
+```bash
+$ ddev restart
+```
diff --git a/doc/src/usage/ddev-start.md b/doc/src/usage/ddev-start.md
new file mode 100644
index 0000000..49ef271
--- /dev/null
+++ b/doc/src/usage/ddev-start.md
@@ -0,0 +1,9 @@
+# ddev start
+
+Starts the environment and boots all the conteiner. This works both to start a
+previously stopped environment, and to start the environment the first time.
+
+**Example:**
+```bash
+$ ddev start
+```
diff --git a/doc/src/usage/ddev-status.md b/doc/src/usage/ddev-status.md
new file mode 100644
index 0000000..f4faac1
--- /dev/null
+++ b/doc/src/usage/ddev-status.md
@@ -0,0 +1,9 @@
+# ddev status
+
+Displays the status of all containers in the environment, including internal
+and external addresses, domains and ports to the terminal.
+
+**Example:**
+```bash
+$ ddev status
+```
diff --git a/doc/src/usage/ddev-stop.md b/doc/src/usage/ddev-stop.md
new file mode 100644
index 0000000..9822f61
--- /dev/null
+++ b/doc/src/usage/ddev-stop.md
@@ -0,0 +1,9 @@
+# ddev stop
+
+Stops the environment and all the containers. Useful when you're done with
+your session for now, but may want to continue at a later time.
+
+**Example:**
+```bash
+$ ddev stop
+```
diff --git a/doc/src/usage/testing/README.md b/doc/src/usage/testing/README.md
new file mode 100644
index 0000000..f00b526
--- /dev/null
+++ b/doc/src/usage/testing/README.md
@@ -0,0 +1 @@
+# Testing