CloudFlow Console Reference Application

Overview

This codebase provides a starter kit that provides out-of-the-box integrations with the CloudFlow platform.

Use this codebase to build a more tailored portal experience for your users to interact with your product while abstracting the CloudFlow administrative interface.

License to Use

CloudFlow grants permission to users of this Console Reference Application code to use, modify and build upon the code ongoing as needed, free of charge, for the purpose of building a tailored portal experience. CloudFlow grants these rights to current paying customers. This portal code is provided for reference purposes only and provided as-is with no warranties.

This is provided on the condition that the code is not:

1. Open sourced.
2. Made available to other parties outside of the conditions highlighted herein.
3. Used for purposes outside the scope of building a tailored portal for access to the CloudFlow platform.
4. Separately resold - either as a one-off or subscription service (royalties or license fees may apply without prior approval from CloudFlow).

Tools and technologies

This project is built upon Laravel, a PHP application framework. Services required to run this application (Nginx webserver, php-fpm, MySQL) are provided as docker images (see dockerfiles/* and docker-compose.yml for more detail).

Tooling required to develop on this codebase (e.g Composer, NodeJS) are included in the PHP image, and wrapper commands exist for ease of use (e.g ahoy composer and ahoy npm).

The following tools are required in your local development environment:

• Ahoy CLI
• Docker and Docker Compose

Getting Started

Initial configuration

The majority of configuration required happens in the .env file. This file injects environment variables to the running application.

To begin, copy the .env.example file to .env and edit in your favorite text editor.

Basic configuration

Start by editing the following values:

• APP_NAME: The application name
• APP_COMPANY_NAME: Your company name
• APP_COMPANY_URL: Your company URL
• MAIL_FROM_ADDRESS: The from email address associated with outgoing mail
• MAIL_FROM_NAME: The from name associated with outgoing mail

These values are used throughout the portal, in email notifications, and on invoices (if Subscriptions are enabled).

Connect to your CloudFlow account by modifying the following values:

• SECTION_ACCOUNT: Your CloudFlow account ID
• SECTION_APPLICATION_STACK: The name of the stack to provision on create
• SECTION_CONFIG_FILE: Path to custom JSON file in the repository
• SECTION_AUTH: Basic authentication credentials for Aperture, create with echo -n user:password | base64

reCAPTCHA support

By default Google reCAPTCHA is enabled on the user registration form. This prevents spam registrations and is generally recommended.

1. Create a new v2 "I'm not a robot" tickbox from the reCAPTCHA dashboard.
2. Add "localhost" as a domain for local development, plus any other domains the application will run on.
3. Add the site key to the NOCAPTCHA_SITEKEY value in .env.
4. Add the secret key to the NOCAPTCHA_SECRET value in .env.

If you wish to disable reCAPTCHA set the NOCAPTCHA_ENABLED value to false.

Building the project

Once all required software packages and basic configuration values are present we can build the project. To do this run the following command:

ahoy build

This will build docker images and run local containers. It will also import database schema and import seed data. You should see the following info on success:

  --- App Info ---

  Site:  http://localhost:8002

  Mailhog:  http://localhost:8026

  Maria port: 3307

Visit the project on http://localhost:8002 to get started.

Configuring look & feel

The starter kit provides some simple variables to alter color scheme and logo. Edit the resources/sass/_variables.scss file to update path to logo file (SVG recommended) and colors.

Once changes have been made you will need to recompile the frontend assets. Do this with:

ahoy npm run production

If you wish to build non-minified versions for debugging build with:

ahoy npm run development

You should commit the resulting built artefacts to the repository.

Mailhog & Email configuration

Mailhog is an application that traps outgoing emails to make local development easier. This application runs Mailhog and is configured to trap email by default.

To view the Mailhog interface run ahoy info for the local service URL. Any verification, password reset, notification emails will be sent here.

Configuring email

Many email providers are supported, including Mailgun, Postmark, AWS SES, SMTP, sendmail. Read the Laravel docs for detail on configuring the mail driver in the .env file.

To set the email sender address and name, use the following settings:

EMAIL_ADDRESS_FROM=info@example.com

EMAIL_ADDRESS_NAME=Info

Email verification

To require users to verify their email address for their account to have full access set the following in the .env file:

EMAIL_VERIFY_REQUIRED=true

Billing and subscriptions

A simple subscriptions, billing and invoices solution is included in the starter kit. This allows for simple SaaS-like products to be built on the CloudFlow platform with minimal effort.

By default, subscription services are enabled. Subscription services are broken into two main categories: individuals and organizations. Organizations allow for teams to be created and users to be invited to access an account with varying levels of permission.

Out of the box, subscription features place limits on the numbers of projects and team members that can be created based on a number of customizable tiers defined in code.

To disable the need for a subscription to enable all features, set the following in the .env file. Alternatively, a specific individual/organization can be assigned the 'unlimited' subscription.

SUBSCRIPTIONS_ENABLE=false

Production deployments

To run in a production environment the following changes should be made in the .env file.

APP_DEBUG=false

APP_URL=https://www.production-domain.com

PROD_MODE=true

Ensure the following SECTION_AUTH env variable contains valid authentication with access to your production applications and environments.

If Subscriptions/Billing is active ensure the following values are provided:

STRIPE_KEY_PROD

STRIPE_SECRET_PROD

Database values (DB_*) should be updated to point to a production database service. While it is possible to use the provided MySQL container it is not recommended, as it represents a SPOF (single point of failure). A cloud service like AWS, Azure, Google Cloud.

Email should be configured as per the "Configuring email" section above.

Help, Support and Professional Services

This reference portal application is provided as-is with no CloudFlow specific support provided. If you would like help building on the scope of this codebase outside the reference application itself, we can facilitate a relationship with our partner QuantCDN who are experts in building portal applications on top of this reference application. They are able to work with you in a Professional Services capacity to customize this console experience.

Contact CloudFlow at se@section.io and we will be happy to set up that connection.