# Usage

## Quick examples

- Start a Nextcloud instance with `postgresql`, and `s3` primary storage:

  ```bash
  haze start pgsql s3
  ```

- Start a Nextcloud instance with `sqlite`, `php 8.3` and an `smb` external
  storage:

  ```bash
  haze start 8.3 smb
  ```

- Run specific units test against an `oracle` database
  ```bash
  haze test oracle apps/dav/tests/unit/Connector/Sabre
  ```

## Managing instances

### Starting an instance

```bash
haze start [--name <name>] [--detach] [database] [php-version] [services] [vX.Y.Z]
```

Where `database` is one of `sqlite`, `mysql`, `mariadb`, `pgsql` or `oracle`
with an optional version (e.g. `pgsql:12`), defaults to `sqlite`. And
`php-version` is one of `8.0`, `8.1`, `8.2`, `8.3`, `8.4` or `8.5`, defaults to
the maximum version support by the current Nextcloud version.

You can specify a version number (e.g. `v32.0.2`) to use the sources from a
release instead of using the local sources.

Use `--name <name>` to give the instance a specific name instead of a randomly
generated one. For example:

Use `--detach` to give the instance
[its own sources](#instances-with-their-own-sources) instead of sharing
`sources_root` with all other instances.

See the [services documentation](./services.html) for a list of available
services.

### List running instances

```bash
haze
```

or

```bash
haze list
```

### Stop an instance

```bash
haze [match] stop
```

### Remove all unpinned running instances

```bash
haze clean
```

### Pin an instance

```bash
haze [match] pin
```

Pinned instances will not be removed by `haze clean`.

### Unpin an instance

```bash
haze [match] unpin
```

## Run commands in a temporary instance

```bash
haze shell [database] [php-version] [services] [cmd]
```

This will create an instance, run the provided command, and cleanup the
instance.

If no `cmd` is specified it will launch `bash`

## Run tests in a new instance

```bash
haze test [database] [php-version] [services] [phpunit version] [path]
```

Where `path` is a file or folder to run PHPUnit in, relative to the sources
root.

This will create a fresh instance, run the PHPUnit tests, and clean up the
created instance.

## Interacting with running instances

The following commands run against the most recently started instance by default
and allow optionally providing a `match` to select a specific instance by its
name.

### Open an instance in the browser

```bash
haze [match] open
```

### Execute a command on an instance

```bash
haze [match] [service] [cmd]
```

If no `cmd` is specified it will launch `bash`

If a service name or `db` is provided, the command will be in the container of
the service or database.

If no `cmd` is specified it will launch `bash`

### Execute an occ command on an instance

```bash
haze [match] occ [cmd]
```

### Connect to the database on an instance

```bash
haze [match] db
```

### Show the logs of an instance

```bash
haze [match] logs
```

### Edit a file in an instance with the local $EDITOR

```bash
haze [match] edit <path>
```

Where `<path>` is the path of a file inside the container, for example
`config/config.php`.

### Reload the PHP configuration of an instance

```bash
haze [match] reload
```

The PHP configuration can edit changed with `haze edit  /config/php.ini`

### Run a command with instance environment variables set

```bash
haze [match] env <cmd> [args]
```

Runs the provided command with `NEXTCLOUD_URL`, `DATABASE_URL` and `REDIS_URL`
environment variables set for the matched instance.

This is intended to run a local
[push daemon](https://github.com/nextcloud/notify_push) against an instance.

## Git tools

Haze provides a couple of utilities to make working with many git repositories
for apps easier.

### Checkout a branch for all local apps

```bash
haze git checkout [branch]
```

Checks out the branch in all git repositories within the apps folder.

Defaults to the branch matching the current checked out server versions (e.g.
`master` or `stable33`).

`master` and `main` can be used interchangeably.

### Pull remote changes for all local apps

```bash
haze git pull
```

Performs a pull in all git repositories within the apps folder.

## Update the container images

```bash
haze update
```

## Instances with their own sources

By default every instance shares the sources configured as `sources_root`, so
all instances always run the same code. An instance started with `--detach` gets
its own `git worktree` of `sources_root` instead, created in `worktree_dir`,
which lets you run several instances on different branches at the same time.

```bash
haze start --name my-fix --detach
```

The worktree is checked out with a detached head. Every app in one of the
`app_directories` that gets enabled during setup receives its own worktree as
well, other apps keep running from the shared app directory.

The worktrees are removed together with the instance, by `haze stop` or
`haze clean`.