Configuration and Setup

Configuration & Setup

Introduction

ZippyBox comes packaged with a command-line setup utility that will get you up and running in a few minutes. It will attempt to automatically configure ZippyBox and create a default user account and workspace for administrative purposes.

Alternatively, you can configure ZippyBox by using the Setup Wizard, or by following the Manual Configuration section below.

Once you have successfully setup ZippyBox, you must also follow the Additional Configuration instructions below.

For security reasons, we recommend setting up ZippyBox as soon as possible after installation.

Setup Command

In the ZippyBox installation's root directory, run the following command:

php artisan sp:install

The command will prompt you for confirmation on most steps. If this is the first time running setup for an installation, you should answer yes to the prompts in order to ensure that ZippyBox is completely set up as expected.

You can safely run the command multiple times if needed.

Once the setup command has completed, you will need to move onto the Additional Configuration section in order to correctly configure how ZippyBox dispatches your messages.

Setup Wizard

You can also use a Setup Wizard to guide you through the installation process. If you are hosting ZippyBox at campaigns.example.com, just point your browser to campaigns.example.com/setup to launch the setup process.

In order to launch the Setup Wizard the .env file must already be present in the root folder of your installation, and the encryption key must be set. See the Manual Configuration section below for more information.

Once your first user has been created, the Setup Wizard will no longer be available.

Once the Setup Wizard has completed, you will need to move onto the Additional Configuration section in order to correctly configure how ZippyBox dispatches your messages.

Manual Configuration

Creating Configuration File

ZippyBox's configuration is handled through the.env file. By default, this file does not exist. To create it manually, you will need to clone the included .env.example, rename it to .env and make changes as necessary.

Any keys that are set in the .env file will be used, even if they are blank. If you do not wish to actively set a key, you should remove it from your .env file, rather than leave it blank.

Key Generation

If you did not run the setup command, or if for some reason the APP_KEY value is empty, you will need to create an encryption key. This is used by ZippyBox to apply encryption to things like user sessions.

To generate a new key, you should run the following command:

php artisan key:generate

Although key generation can be run again, this will invalidate any sessions or make any stored encrypted data inaccessible. You should not generate a new key unless absolutely necessary.

Base URL

You will need to set the APP_URL variable in the .env file to the base URL for your installation of ZippyBox.

For example, if you are hosting your installation of ZippyBox at campaigns.example.com, you will need to set the following:

APP_URL=https://campaigns.example.com

This is necessary to allow ZippyBox to correctly generate unsubscribe links, or links for user registration emails.

Database Connection

In order for ZippyBox to connect to your database, you must set the database configuration values in the .env file.

Firstly, you need to specify what type of database you are using by setting the DB_CONNECTION value to either mysql for a MySQL database or pgsql for a PostgreSQL database.

Secondly, you need to set the connection details for your database installation. The following values need to be set:

  • DB_HOST – This is the host of your database, e.g. 127.0.0.1 for a local installation
  • DB_PORT - The port ZippyBox should use to talk to your database
  • DB_DATABASE – The database ZippyBox should use to store its data
  • DB_USERNAME – The username ZippyBox will use to authenticate itself with your database
  • DB_PASSWORD – The password ZippyBox will use to authenticate itself with your database

Database Migrations

To set up the database schema, migrations must be run. Migrations are instructions an application uses to configure database schema, running in sequence from beginning to end in order to ensure that the database is set up as the application expects it to be.

Do not make custom modifications to the database yourself. Any database changes that ZippyBox requires should be accomplished through the running of migrations.

Before running migrations, ensure that you have correctly configured your database connection, as schema changes will be made.

The included command-line setup command will run migrations for you (after a prompt), but you can run migrations manually using the following command:

php artisan migrate

Publishing Vendor Files

Run the following command to publish the config, views, languages and assets from ZippyBox to your project:

php artisan vendor:publish --provider=ZippyBox\\Base\\ZippyBoxBaseServiceProvider

Workspaces & Users

If you do not use the setup command to create a workspace and user with which to administer ZippyBox, you will need to go through the web interface registration process.

You must follow the User Management Email configuration specified in Additional Configuration in order to allow registration and user invitation in ZippyBox.

Additional Configuration

Cron Jobs

ZippyBox makes use of regular background tasks and it is therefore essential to create a cron job to run every minute:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Please refer to the Laravel documentation on Task Scheduling (opens in a new tab) for further information.

Message Sending & Queues

ZippyBox sends email messages using a queue system. The queue can be processed synchronously or asynchronously. Asynchronous queues can be handled via your primary database or via redis.

You can specify which queue driver to use in the QUEUE_CONNECTION parameter in the .env file. This should be set to one of sync, database or redis, depending on your requirements. This configuration applies to all messages sent in ZippyBox and cannot be changed on a per-user, per-workspace or per-provider basis.

Sync

The synchronous queue runs any queued jobs as they are requested, requiring the user to wait until the job has been completed before any further action can be taken.

This has the advantage of being simple and requiring no additional configuration. However, as this does not scale well, this approach is only recommended for relatively small message sending requirements.

To use the synchronous queue, you only need to set the QUEUE_CONNECTION to sync, and no further configuration is required.

Database

Processing asynchronous queues via the database is considered a middle option. Running an asynchronous queue avoids the issues that come up using a synchronous queue, as messages can be processed without blocking further action being taken by the user, and will work until all jobs are completed regardless of how long it takes.

The advantage of using the database for running the asynchronous queue is that it requires no extra services to be run, as it uses the primary database (MySQL or Postgres) that you have already configured for ZippyBox.

The main disadvantage is that under heavy workloads the queue can negatively affect the performance of the database.

As such, the database queue is recommended for small to medium sized mailing lists.

To use the database driver, you must first set the QUEUE_CONNECTION to database in your .env file. You also need to run the following commands, which will create a new jobs table in your database, which that will be used to manage the queue.

php artisan queue:table
php artisan migrate

Redis

Redis is the recommended solution for running medium to large mailing lists.

You will of course need an installation of redis on your server. You will then need to set the QUEUE_CONNECTION to redis and set the following configuration values in your .env file:

  • REDIS_HOST
  • REDIS_PASSWORD
  • REDIS_PORT

Running the queue without Laravel Horizon

If you don't want to use Horizon to manage you redis queue or you're using the database driver you will have to run a queue worker (opens in a new tab) for each queue that ZippyBox uses.

  • ZippyBox-message-dispatch: dispatches messages to the email service
  • ZippyBox-webhook-process: processes incoming webhooks
php artisan queue:work --queue=ZippyBox-message-dispatch
php artisan queue:work --queue=ZippyBox-webhook-process

Running Redis Queues With Laravel Horizon

ZippyBox bundles Laravel Horizon (opens in a new tab) as an easy way to run and manage redis queues.

Configuration for the queues necessary to run ZippyBox is already included. In order to use Horizon as your queue manager, you should first publish the Horizon assets:

php artisan horizon:publish

To start processing your queue items with Horizon, you simply need to run the following command:

php artisan horizon

When using Horizon in production, you should consider using a service to ensure the queue runner restarts if it fails for any reason. The Horizon documentation has a guide (opens in a new tab) on how to use Supervisor to do this.

Autoscaling

The configuration for Horizon included with ZippyBox allows autoscaling of queue workers. By default, webhooks received and messages sent via the queue each have a minimum of 2 processes running, and a maximum of 10 or 20. If these values do not suit your requirements, they can be adjusted in the config/horizon.php file—in particular supervisor-2 and supervisor-3—using the minProcesses and maxProcesses values.

User Management Email

In order to use user management functionality (for example, inviting new users or password resets) in ZippyBox, it is necessary to set up an email service that ZippyBox can use to send the messages.

If you are not going to be inviting any other users or team members to your ZippyBox installation, then this section can be ignored.

There is no relationship between ZippyBox's internal mail configuration and any email services that are configured for a workspace.

You will need to set ZippyBox_REGISTER=true in the .env file in order to use the registration and user invitation functionality.

By default, users are granted the ability to reset their passwords. If you wish to disable password resets, you must set ZippyBox_PASSWORD_RESET=false in the .env file.

You first need to set MAIL_MAILER to your chosen service. The options here are smtp, sendmail, ses, mailgun and postmark.

SMTP & Sendmail

When using a regular SMTP provider, or sendmail, you should set the following configuration values:

  • MAIL_HOST – This is the host for the SMTP server
  • MAIL_PORT – This is the port that will be used to connect to the SMTP server
  • MAIL_USERNAME – The username used to authenticate with the SMTP server
  • MAIL_PASSWORD – The password used to authenticate with the SMTP server
  • MAIL_FROM_ADDRESS – The address that mail will appear to come from
  • MAIL_FROM_NAME – The name that mail will appear to come from

SES

When using SES as your mail service, you should set the following configuration values, adding them to the .env file if they are not already present:

  • AWS_ACCESS_KEY_ID – Your AWS ID key
  • AWS_SECRET_ACCESS_KEY – Your AWS secret key
  • AWS_DEFAULT_REGION – Your AWS region (defaults to us-east-1 if not included in the configuration file)

Mailgun

When using Mailgun as your mail service, you should set the following configuration values, adding them to the .env file if they are not already present:

  • MAILGUN_DOMAIN
  • MAILGUN_SECRET
  • MAILGUN_ENDPOINT – (defaults to api.mailgun.net if not included in the configuration file)

Postmark

When using Postmark as your mail service, you should set the following configuration values, adding them to the .env file if they are not already present:

  • POSTMARK_TOKEN
SMTPTemplates