Helium

Helium

Helium is a Fast, Secure and Reliable Newsletter System. Helium is perfect for weekly articles newsletter, featured articles newsletter, marketing campaigns or even product updates. It integrates easily with most of SMTP providers out there. It is built with Symfony 5.4 LTS to support a broad range of PHP versions plus symfony extended support.

Some Features

Easy Setup.
Statistics dashboard with trends in subscribers and newsletters.
Fast email delivery. you can run any number of workers for massive numbers of subscribers and newsletters.
Scheduled newsletters support.
Customizable newsletter page.
Customizable newsletter emails.
Powerful templating engine for newsletter emails.
Powerful templating engine for newsletter page.
Search engine optimized.
Integrates easily with any SMTP services like Postfix, Gmail, SendGrid, Sendinblue, Postmark, Mailgun, Mailchimp, Amazon SES, Mailtrap.
Automated deployment and upgrades with Ansible.
Translation Ready.
Fully Ajax.
Developer Friendly.
Well documented code.
Amazing Support.

Free Hosting

You can get at least 3 months of a free hosting to run Helium. Please feel free to use one of the following links to register:

Requirements

Linux Operating System.
Apache or Nginx with PHP-FPM
PHP 7.4+.
MySQL 5+ or MariaDB.
Composer.

We suggest using a Virtual Server (VPS) not shared hosting since Helium requires a two running background process to send emails on time. You can get a free VPS for at least three months, Please check free hosting section

Manual Installation

Please follow this guide to install ubuntu 22.02 with Nginx, MySQL, PHP-FPM
if you deployed helium to this path /var/www/project/ you need to create two systemd services.
To install PHP packages optimized for production.

$ make prod_composer

To migrate the database, you can use the following command

$ make migrate

The watcher systemd service.

$ nano /etc/systemd/system/watcher.service

[Unit]
Description=Helium Watcher
After=network.target

StartLimitIntervalSec=500
StartLimitBurst=5

[Service]
User=root
Group=www-data
WorkingDirectory=/var/www/project
Restart=on-failure
RestartSec=5s
Environment=LANG=en_US.UTF-8
Environment=LC_ALL=en_US.UTF-8
Environment=LC_LANG=en_US.UTF-8
ExecStart=php /var/www/project/bin/console watch
ExecReload=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s TERM $MAINPID
PrivateTmp=true

[Install]
WantedBy=multi-user.target

The worker systemd service.

$ nano /etc/systemd/system/worker.service

[Unit]
Description=Helium Worker %i
After=network.target

StartLimitIntervalSec=500
StartLimitBurst=5

[Service]
User=root
Group=www-data
WorkingDirectory=/var/www/project
Restart=on-failure
RestartSec=5s
Environment=LANG=en_US.UTF-8
Environment=LC_ALL=en_US.UTF-8
Environment=LC_LANG=en_US.UTF-8
ExecStart=php /var/www/project/bin/console messenger:consume async
ExecReload=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s TERM $MAINPID
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Then enable and start them

$ systemctl enable watcher
$ systemctl start watcher

$ systemctl enable worker@1
$ systemctl start worker@1

Installation with Ansible (preferred)

You need to install Python 3 locally and use a laptop that has SSH access to the production Linux server. Then please follow these steps:

Create a python virtual environment.

$ python3 -m venv venv
$ source venv/bin/activate

Install ansible

$ make config

Create hosts.prod from hosts file and replace 127.0.0.1 with the host IP.
Create prod.vault.yml with these configs.

$ ansible-vault create prod.vault.yml

install_mysql: true
root_username: root
root_password: R2ZBmTR6nED6a71AxeTO2DSck
app_db_name: helium
app_db_username: admin
app_db_password: R2ZBmTR6nED6a71AxeTO2UIok
allow_access_from: "127.0.0.1"

install_nginx: true

install_php: true
php_version: 8.1 # or 7.4 on Ubuntu 20.04

install_composer: true

install_postfix: false
postfix_hostname: helium
smtp_sasl_security_options: noanonymous
smtp_sasl_auth_enable: 'yes'
smtp_use_tls: 'yes'
smtp_server: smtp.gmail.com
smtp_port: 587
smtp_username: ''
smtp_password: ''
inet_interfaces: 127.0.0.1

Postfix is disabled but it can be enabled by setting install_postfix: true above and providing the SMTP Server, username and password. You can use your gmail account as an SMTP server by doing the following:

The SMTP server will be smtp.gmail.com and port 587
The SMTP username is your gmail email address.
The SMTP password can be generated after enabling two factor authentication. Please check this guide to generate the app password https://www.golinuxcloud.com/gmail-smtp-relay-server-postfix/.

Run ansible playbook to setup the server

$ make prod

Here is an article explaining the above steps in more details

To Deploy Helium Application:

The following steps will require you to upload the code to a private github or gitlab repository, Add the host public key as a deploy key Then provide the repository git link.

Create helium.vault.yml with these configs.

$ ansible-vault create helium.vault.yml

app_user: appmgmt
app_group: appmgmt

app_version: 1.0.0
git_repo: git@github.com:$AUTHOR/$REPO.git

workers_counts: 1

hostname: helium.com

php_version: 8.1 # or 7.4 on Ubuntu 20.04

app_db_name: helium
app_db_username: admin
app_db_password: R2ZBmTR6nED6a71AxeTO2UIok

app_secret: 3999bf7e3a408f15942779447e01dd7a
app_timezone: UTC
app_env: prod
app_locale: en
messenger_transport: doctrine://default
mailer_dsn: sendmail://default

Please not that mailer_dsn can be one of the following forms:

# If Amazon Mailer
mailer_dsn: ses://ACCESS_KEY:SECRET_KEY@default?region=eu-west-1
mailer_dsn: ses+smtp://ACCESS_KEY:SECRET_KEY@default?region=eu-west-1

# If Mailchimp
mailer_dsn: mandrill://KEY@default
mailer_dsn: mandrill+smtp://USERNAME:PASSWORD@default

# If mailgun
mailer_dsn: mailgun://KEY:DOMAIN@default?region=us
mailer_dsn: mailgun+smtp://USERNAME:PASSWORD@default?region=us

# If Mailjet
mailer_dsn: mailjet+api://PUBLIC_KEY:PRIVATE_KEY@api.mailjet.com
mailer_dsn: mailjet+smtp://PUBLIC_KEY:PRIVATE_KEY@in-v3.mailjet.com

# If Postmark
mailer_dsn: postmark://ID@default

# If Sendgrid
mailer_dsn: sendgrid://KEY@default

# If Sendinblue
mailer_dsn: sendinblue+api://KEY@default
mailer_dsn: sendinblue+smtp://USERNAME:PASSWORD@default

# If Mailtrap
mailer_dsn: smtp://USERNAME:PASSWORD@smtp.mailtrap.io:2525?encryption=tls&auth_mode=login

Run ansible playbook to deploy Helium application.

$ make helium

Configuration

Once you have installed Helium on a server. Please follow the following steps setup the application and also send your first newsletter:

Visit Helium URL and it will redirect to /install page. You will need to provide the application and admin data.

Then you can login with the Admin Email and Admin Password.

It is optional to update your profile. Inserting your first and last name.

It is optional to update the settings.

Then we need to add our first subscriber. Please use your personal email. You can either subscribe from the homepage like other users or insert the email manually from the dashhboard.

Now we can send our first newsletter:
- Open Newsletters then click Add New button.
- Provide the newsletter name for example PHP Weekly Newsletter
- Select delivery to be now or anytime in the future.
- Select Template, the default values will show on template Inputs, you must change these values to your linking.
- A button preview will show up once you update either the template or inputs to view the newsletter.
- For more info how these template works, please check the advanced section.
- Once you click submit with a delivery now, Helium will start sending emails immediately.

Advanced

Which template engine helium is using?

Helium uses the symfony default templating engine Twig. Here is a guide how to use twig

How to build a new home page template?

By default helium scans the templates/default/page/home.$layout.html.twig. To create a new layout called creative. create a new file templates/default/page/home.creative.html.twig from templates/default/page/home.default.html.twig. then customize the look and feel.

You can activate the new layout from the dashboard > settings page, select the creative layout.

How to build a new newsletter email template?

Let's create a new newsletter template for product updates. First we create templates/default/newsletter/product_updates.distro.html.twig and templates/default/newsletter/product_updates.distro.yml.

By default the following variables are available to be used in your newsletter template

app_name
app_url
data.unsubscribe_url

You can define some dynamic data in templates/default/newsletter/product_updates.distro.yml

logo_url: 'https://via.placeholder.com/360x170'

updates:
  -
    title: How to Setup a HA Cassandra Cluster
    img_url: 'https://via.placeholder.com/1200x700'
    link: 'https://clivern.com/how-to-setup-a-ha-cassandra-cluster/'
    description: >-
      Apache Cassandra is a NoSQL database with flexible deployment options that’s
      highly performant (especially for writes), scalable, fault-tolerant, and
      proven in production. Alternative NoSQL databases include Amazon DynamoDB,
      Apache HBase, and MongoDB.
  -
    title: How to Setup a HA Cassandra Cluster
    img_url: 'https://via.placeholder.com/1200x700'
    link: 'https://clivern.com/how-to-setup-a-ha-cassandra-cluster/'
    description: >-
      Apache Cassandra is a NoSQL database with flexible deployment options that’s
      highly performant (especially for writes), scalable, fault-tolerant, and
      proven in production. Alternative NoSQL databases include Amazon DynamoDB,
      Apache HBase, and MongoDB.

  -
    title: How to Setup a HA Cassandra Cluster
    img_url: 'https://via.placeholder.com/1200x700'
    link: 'https://clivern.com/how-to-setup-a-ha-cassandra-cluster/'
    description: >-
      Apache Cassandra is a NoSQL database with flexible deployment options that’s
      highly performant (especially for writes), scalable, fault-tolerant, and
      proven in production. Alternative NoSQL databases include Amazon DynamoDB,
      Apache HBase, and MongoDB.

You can access the above data from the template using data.logo_url and data.updates like the following

{% for update in data.updates %}
    <img src="{{ update.img_url }}">
    <table>
        <tbody>
            <tr>
                <td >
                    <h1>{{ update.title }}</h1>
                    <p>{{ update.description }}</p>
                    <a href="{{ update.link }}">
                        <span>Learn more</span>
                    </a>
                </td>
            </tr>
        </tbody>
    </table>
{% endfor %}

Please note that all variables in the product_updates.distro.yml can be accessed by data.$$

Translation

Please translate the messages.xlf included with the release files and send the translated file to hello@clivern.com.

<?xml version="1.0" encoding="utf-8"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:1.2" version="1.2">
  <file source-language="en" target-language="fr" datatype="plaintext" original="file.ext">
    <header>
      <tool tool-id="symfony" tool-name="Symfony"/>
    </header>
    <body>
      <trans-unit id="TnDx.SS" resname="Reset Password">
        <source>Reset Password</source>
        <target>réinitialiser le mot de passe</target>
      </trans-unit>

Support

Please read help files included with my items before anything.

Support for my items includes:

Answering technical questions about item’s features.
Assistance with reported bugs and issues.
Providing updates to ensure compatibility with new software versions.
Help with included 3rd party assets.

Support for my items do not include:

Customization and installation services.

Please send any support request to this email hello@clivern.com. We’re glad to help!

- Initial Release.

License

Helium is authored and maintained by @clivern.