Install Dada Mail w/Dada Mail Installer

Installing and Configuring Dada Mail

Audience

The instructions below are tailored for installing Dada Mail on a shared hosting account, running something like a traditional Apache/Perl/MySQL stack. You won't need ssh access, or root privileges or anything like that. If you're running something else, you may want to look at the command line instructions,

https://dadamailproject.com/d/install_dada_mail_cl.pod.html

Overview

Dada Mail comes with a web-based installer to help you out with setting things up. We'll have to first get Dada Mail onto your hosting account. That involves downloading the Dada Mail distribution, uploading it back to your hosting account (along with a helper script called uncompress_dada.cgi), running helper script, then visiting the Installer.

Let's go!

Download the Dada Mail distribution

Download Dada Mail, v11_22_0_stable_2023-09-18

Or, if you're a Pro Dada Subscriber,

Log into your Pro Dada Subscriber area to Download Pro Dada...

When installing Pro Dada, use pro_dada_mail-v11_22_0_stable_2023-09-18.tar.gz as the name of the distribution in these directions.

Upload the Dada Mail distribution

Once you have downloaded the Dada Mail distribution ( dada_mail-v11_22_0_stable_2023-09-18.tar.gz, upload it to your hosting account.

Historically, CGI scripts were installed in your account's cgi-bin directory, but you may be able to install Dada Mail wherever you would like. One suggestion we like is to set up a subdomain (for example: lists.yourdmain.com), then intall Dada Mail in that location. That way, the URL is kept short, and there will be less potential interference between Dada Mail and any other apps you may have running (like Wordpress)

Download, then Upload the helper script

The helper script is called, uncompress_dada.cgi.

Download using the link below - it's a small CGI Perl script - so you will want to save the source you see as a PlainText File - keep the name, uncompress_dada.cgi.

uncompress_dada.cgi for Dada Mail v11_22_0_stable_2023-09-18 (Save Page/Link As...)

and upload the uncompress_dada.cgi script (PlainText/ASCII mode - NOT binary!) to the same directory in your hosting account that you just uploaded, dada_mail-v11_22_0_stable_2023-09-18.tar.gz.

Change the file permissions of the helper script to, "755"

Visit the helper script in your web browser

Visiting the uncompress_dada.cgi script should attempt to uncompress the dada_mail-v11_22_0_stable_2023-09-18.tar.gz and change the necessary permissions of various files and prep the actual installer for you to use.

Once it's finished running, you should be presented with a link to use the actual installer.

Click the link at the bottom of the screen labeled, Continue Installing and Configuring Dada Mail! to continue.

See, Prepping Dada Mail Manually if this doesn't happen and you get a message in your browser window, sort of like this: 

Can't find dada_mail-v11_22_0_stable_2023-09-18.tar to uncompress! You may have to uncompress and prep Dada Mail manually.

Configuring Dada Mail using the Dada Mail Installer

The first screen of the installer will ask you if you'd like to Install, or Upgrade Dada Mail.

Choose, Install and click the button labeled, Continue.

A Warning Up Top?

It's possible that before you even start using the Dada Mail installer, that you'll receive a warning stating that Dada Mail won't be able to edit the, dada/DADA/Config.pm file. This would be because there's a difference in file permissions/privileges between the user that the installer is running under and the user that owns the dada/DADA/Config.pm file.

This means you'll need to edit one line in the dada/DADA/Config.pm file to get Dada Mail running correctly.

".dada_files" Directory Location

The, .dada_files directory is the directory that Dada Mail saves its global configuration file (called, .dada_config); as well as its logs, templates and temporary files. Your mailing lists themselves, and most data Dada Mail creates will be saved in the SQL database.

We suggest having the installer create the, .dada_files directory in your home directory. All you'll need to do is fill out where your home directory is located.

The installer will do its best to pre-fill out its own guess for a good location for you.

Dada Mail URL

The Dada Mail URL is simply the URL that you will access Dada Mail's, mail.cgi script from. This form field should be filled out automatically, but if something doesn't look right, just look at the URL of the installer - for example, if the URL of the installer is:

http://example.com/cgi-bin/dada/installer/install.cgi

Your Dada Mail URL will be:

http://example.com/cgi-bin/dada/mail.cgi

If you do not like the URL of your Dada Mail installation, you will want to move your entire Dada Mail installation, then run the installer again at this new location. Setting this form field to where you would like your Dada Mail installer won't work the way you may hope.

Support Files Directory

Dada Mail needs a collection of static files (image files, css files, javascript files, etc) installed in the right place to work correctly. During configuraation, the installer will copy over these resources to a new directory on your hosting account called, dada_mail_support_files. You will need to tell the installer where this new directory should reside.

Unlike the .dada_files directory, you will want to be able to access the dada_mail_support_files directory through your web browser, so make sure that you pick a publicly accessable directory (a directory you can visit in your web browser).

By default, a pretty good guess is made for the location to set both the Server Absolute Path to your base Public HTML directory, as well as the Corresponding URL to access that same directory through your web browser.

If the default location looks fine, keep it as-is. If you'd like to customize/fix where this directory should live, here's the place to do so.

Make sure That this URL and the Program URL either both domain name, or are located on the same subdomain. The following examples will work great:

Same Domain

Program URL: http://example.com/cgi-bin/dada/mail.cgi

Dada Mail Support Files Dir: http://example.com/dada_mail_support_files

Same Subdomain

Program URL: http://www.example.com/cgi-bin/dada/mail.cgi

Dada Mail Support Files Dir: http://www.example.com/dada_mail_support_files

Same Subdomain

Program URL: http://list.example.com/cgi-bin/dada/mail.cgi

Dada Mail Support Files Dir: http://list.example.com/dada_mail_support_files

The following examples will not work well:

Different Subdomain!

Program URL: http://www.example.com/cgi-bin/dada/mail.cgi

Dada Mail Support Files Dir: http://example.com/dada_mail_support_files

Different Subdomain!

Program URL: http://example.com/cgi-bin/dada/mail.cgi

Dada Mail Support Files Dir: http://list.example.com/dada_mail_support_files

Dada Mail Root Password

The, Dada Mail Root Password is the main administrative password to your Dada Mail installation - choose a good, strong password. This password will be stored in a one-way encrypted form, so there will be no way to retrieve it later on (although there are options available to reset the password later, without having to know the current password).

Dada Mail Backend

Dada Mail will need to save its mailing lists and other information in an SQL database.

Choices: MySQL, PostgreSQL or SQLite

Both MySQL and PostgreSQL will have the same features available and we recommend either equally.

SQLite is also an option, but we recommend using it only for local testing purposes.

When you select one of the SQL backends, you'll also be asked to fill in the SQL connection information, including the database server, the port number, the name of the database itself and the username and password.

You will need to set up this database separately. Note its Server, Database, Username and Password. You will not need to create any tables beforehand. The SQL user will need full priviliges to your database.

For security reasons, we don't suggest giving this same user any permissions to any other database.

Test Your SQL Connection

A button labeled, Test SQL Connection is present - and when pressed, it will run a quick connection test to see if Dada Mail can connect to your SQL server. T his can help you make sure your SQL credentials for Dada Mail are working correctly.

Advanced Configuration (Optional)

As far as needed configuration settings - we're done! Dada Mail's installer does support additional global configuration options.

See the documentation on Advanced Configuration Options

Completing the Installation and Configuration.

Once you've filled out the form correctly, click the button labeled, Configure Dada Mail.

The Installer will configure your Dada Mail.

Once finished, the screen will refresh with the list of steps it has taken.

Required: Set the Cronjob

For many tasks in Dada Mail, including making sure your mass mailings are going out correctly, you will need to set up the scheduled job (cronjob).

The unique command needed to run the required jobs will be shown.

More information on Dada Mail's scheduled job:

https://dadamailproject.com/d/features-scheduled_cronjobs.pod.html

Required: Move the, "installer" directory

Dada Mail will only start working once you've move the, dada/installer directory out of the way. This is a security precaution, so that someone else doesn't come along and attempt to reconfigure your Dada Mail!

The provided button, Move the, 'dada/installer' Directory, Disable the, 'install.cgi' script should do this task, but if it fails (it'll let you know), you'll have to remove it manually.

Do You Need to Manually Edit The, "dada/DADA/Config.pm" File?

There's a possibility, especially if you were issued the warning before filling out the configuration form, that you'll have to edit a line in the dada/DADA/Config.pm file. If this is the case, the installer will show you which file to look for and what to changes need to be done.

Be very careful when editing this file, as any error will stop Dada Mail from working. When saving this file, make sure to upload the file in ASCII/Plain Text mode, NOT binary!

Optional: Install the CPAN Perl Modules

Dada Mail's capability is greatly enhanced by installing the following CPAN Perl Module Bundle:

        Bundle::DadaMailXXL

More Information: Installing CPAN Perl Modules https://dadamailproject.com/d/FAQ-installing_CPAN_Perl_modules.pod.html

Making Additional Edits

The installer should give you the full path to the, .dada_config file it creates. This is the file that is written that holds your configuration that the installer just created. There's a ton of additional configuration options you can set - the installer just gets you up and running correctly.

Making additional configurations is a lot more advanced than running the installer, so be careful when editing this file - make a backup first.

Instructions on how to configure more of Dada Mail's more advanced global features can be found here:

https://dadamailproject.com/d/global_variables.pod.html

Running Dada Mail for the First Time

Once you've gotten the, dada/DADA/Config.pm file edited (if needed) and moved the installer directory out of the way, it's time to begin using Dada Mail.

Press the button labeled, Start Working With Dada Mail to begin!

Good Luck!

Errors When Installing

Sometimes an install doesn't work as planned. If the installer can't continue doing it's job, the last error will be reported in the browser in a, "Yikes!" screen. All errors will be logged in the, installer_errors.txt file one can find within the same directory as the, install.cgi script.

Making Additional Global Configuration Changes using the Dada Mail Installer

Along with installing Dada Mail, the Dada Mail installer can also help reconfigure the global configuration of Dada Mail at any time in the future.

Dada Mail comes with a plugin called, Global Configuration to make this easy. This plugin can be installed using the Dada Mail Installer itself, and should be installed and enabled by default.

Access Global Configuration in the List Control Panel under, Plugins: Global Configuration. Make sure you have logged into your mailing list with the Dada Mail Root Password, as it's not available if you log in with the List Password.

You can also re-enable the Dada Mail Installer Manually:

When asked if you want to Install or, Upgrade your Dada Mail, choose, Upgrade and make sure the text box labeled, Current .dada_files Location is filled in with the correct absolute path to the parent directory that holds your .dada_files directory. Click the button labeled, Continue..., to bring you back to the Configuration screen.

Once you've completed your configuration changes, click the Configure Dada Mail! button as before and follow the same directions you did during the installation, for the next screen.

Additional Perl CPAN modules

Dada Mail's abilities can be greatly extended by the additional installation of a number of Perl CPAN Modules that are available outside of the Dada Mail distribution.

We've bundled a number of these optional modules together, so you just need to install the following Perl module:

Bundle::DadaMailXXL

to gain many of these optional features. We highly recommend this step!

See the separate docs on installing CPAN Modules:

https://dadamailproject.com/d/FAQ-installing_CPAN_Perl_modules.pod.html

Command Line Interface

An alternative command line interface is available:

https://dadamailproject.com/d/install_dada_mail_cl.pod.html

Dada Mail Project

Download

Installation

Support