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.

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.

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¹ to finish the installation and create the administrator account and channel.

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.

Installing Hubzilla

Once the Hubzilla DDEV environment is up and running, you can set up Hubzilla as usual using the Hubzilla Web UI.

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.

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¹ (or by typing ddev mailpit in the terminal.)

Use that to get the registration token you need to register the first user.

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;

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.

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 status

Displays the status of all containers in the environment, including internal and external addresses, domains and ports to the terminal.

Example:

$ ddev status

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:

$ ddev stop

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:

$ ddev start

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:

$ ddev restart

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:

$ ddev delete --omit-snapshot

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.

$ 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.

ddev phpunit

Runs the unit tests in the web container.

Example: Run the unit tests:

$ ddev phpunit

Any additional args¹ will be passed to the PHPUnit executable in the container:

Example: Run only tests with names mathcing "Access":

$ 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.

Testing