Relationship Graph

Relationship Graph
related to related to child of child of duplicate of duplicate of

View Issue Details

IDProjectCategoryView StatusLast Update
0017208phpList 3 applicationInstallationpublic21-06-18 14:00
Reporterrata Assigned To 
PrioritynormalSeverityminorReproducibilityhave not tried
Status resolvedResolutionfixed 
Summary0017208: Give an example for (at least) debian based distros ?
DescriptionGiving an example of how to install phplist on debian based distros should be really easy.

That, as a side effect, also says what is needed to install, permissions to give to the files, how to create a mysql db+user with proper permissions (more than select+insert is needed to run upgrades), etc.

I think it should be like 5-10 lines long and make installment way more easy. I can do it if you want. What do you think ?
Tagsdocumentation

Relationships

related to 0017207 resolvedgingerling Installation doesn't say to have a "DirectoryIndex index.php index.html" 

Activities

gingerling

04-06-14 10:16

manager   ~0053862

Yes, I would like this, we can put it in the blog (if you like) - I will eventually have to document all of this but it will take me a long time. If this is okay with Michiel it could be your first blog ;)

michiel

08-06-14 10:02

administrator   ~0053883


ok, so, rodrigo to write and then I will review

rata

09-06-14 16:28

updater   ~0053889

What do you think of something like:


Here is an example for installing phplist 3.0.6 on a debian-based distro
(Debian, Ubuntu, etc.). It should be pretty similar with other versions. You can
download latest .tar.gz from http://www.phplist.com/download

So, to install phplist 3.0.6, you can do something like:

 # Install deps (you can use some other PC as the mysql server too)
 apt-get install apache2 libapache2-mod-php5 mysql-server php5-mysql

 # Create a mysql db and user. Choose option 2 ("Create a database + user
 # privilege for that database...")
 # Remember these settings (dbname, username and password) and be sure to only
 # allow host "localhost"
 mysql_setpermission

 # Give full permissions to that user on that DB. Use option 6 ("Create/append
 # full privileges for an existing database") and repeat the same settings
 # TODO: ask M which permissions are needed exactly, THINK for migrations full
 # is needed
 mysql_setpermission

 # Uncompress
 tar xf phplist-3.0.6.tgz
 cd phplist-3.0.6/

 # Give apache proper permissions
 chown www-data: public_html/ -R

 # Configure the db on phplist
 # Make sure to configure, according to the db you just created:
 # database_host
 # database_name
 # database_user
 # database_password
 vim public_html/lists/config/config.php

 # Move to proper location
 mkdir -p /var/www/phplist
 mv public_html/ /var/www/phplist/

 # Create an apache vhost (yes, you can c&p this in your console and it should
 # work)
 cd /etc/apache2/sites-available
 cat << EOF > phplist.conf
<VirtualHost *:80>
        ServerName newsletter.example.com
        ServerAdmin sysadmin@example.com

        DocumentRoot /var/www/phplist/public_html
        DirectoryIndex index.php index.html
        <Directory />
                Options FollowSymLinks
                AllowOverride None
        </Directory>
        <Directory /var/www/>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride None
                Order allow,deny
                allow from all
        </Directory>

        ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
        <Directory "/usr/lib/cgi-bin">
                AllowOverride None
                Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
                Order allow,deny
                Allow from all
        </Directory>

        ErrorLog ${APACHE_LOG_DIR}/error.log

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn

        CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

EOF

 # Edit ServerName and ServerAdmin
 vim phplist.conf

 # Enable vhost
 a2ensite phplist

 # Restart apache
 /etc/init.d/apache2 restart

 # Make sure your ServerName points to this PC

 # In your browser, go to http://<ServerName>/lists/admin and finish the phplist installation

 # Review other settings in the config to make it useful (like PHPMAILERHOST,
 # TEST, bounce_mailbox, etc.)

rata

09-06-14 16:44

updater   ~0053890

Here is again, fixed an issue with allow overrides (didn't realize there are .htaccess files until #17207):


Here is an example for installing phplist 3.0.6 on a debian-based distro
(Debian, Ubuntu, etc.). It should be pretty similar with other versions. You can
download latest .tar.gz from http://www.phplist.com/download [^]

So, to install phplist 3.0.6, you can do something like:

 # Install deps (you can use some other PC as the mysql server too)
 apt-get install apache2 libapache2-mod-php5 mysql-server php5-mysql

 # Create a mysql db and user. Choose option 2 ("Create a database + user
 # privilege for that database...")
 # Remember these settings (dbname, username and password) and be sure to only
 # allow host "localhost"
 mysql_setpermission

 # Give full permissions to that user on that DB. Use option 6 ("Create/append
 # full privileges for an existing database") and repeat the same settings
 # TODO: ask M which permissions are needed exactly, THINK for migrations full
 # is needed
 mysql_setpermission

 # Uncompress
 tar xf phplist-3.0.6.tgz
 cd phplist-3.0.6/

 # Give apache proper permissions
 chown www-data: public_html/ -R

 # Configure the db on phplist
 # Make sure to configure, according to the db you just created:
 # database_host
 # database_name
 # database_user
 # database_password
 vim public_html/lists/config/config.php

 # Move to proper location
 mkdir -p /var/www/phplist
 mv public_html/ /var/www/phplist/

 # Create an apache vhost (yes, you can c&p this in your console and it should
 # work)
 cd /etc/apache2/sites-available
 cat << EOF > phplist.conf
<VirtualHost *:80>
        ServerName newsletter.example.com
        ServerAdmin sysadmin@example.com
        DocumentRoot /var/www/phplist/public_html

        <Directory />
                Options FollowSymLinks
                AllowOverride None
        </Directory>
        <Directory /var/www/phplist/public_html>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride All
                Order allow,deny
                allow from all
        </Directory>

        ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
        <Directory "/usr/lib/cgi-bin">
                AllowOverride None
                Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
                Order allow,deny
                Allow from all
        </Directory>

        ErrorLog ${APACHE_LOG_DIR}/error.log

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn

        CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

EOF

 # Edit ServerName and ServerAdmin
 vim phplist.conf

 # Enable vhost
 a2ensite phplist

 # Restart apache
 /etc/init.d/apache2 restart

 # Make sure your ServerName points to this PC

 # In your browser, go to http://<ServerName>/lists/admin [^] and finish the phplist installation

 # Review other settings in the config to make it useful (like PHPMAILERHOST,
 # TEST, bounce_mailbox, etc.)

michiel

10-06-14 10:43

administrator   ~0053896


There are at least two sides to installing phpList on any server, including Debian.

- Web
- Mail

So, providing a Vhost is one step, the other one would be how to set up the mail side of things.

Setting up mail would include SPF, DKIM and others.

So, for now, writing some docs about the Vhost will be useful, but why not start a Github project to manage the packaging stuff needed to wrap phpList in a debian package, so that a Debian admin can do "apt-get install phplist"

The package would need to:

1. handle dependencies (I think the ckeditor, phpMailer and jQuery are already packages)
2. set itself up in a standard debian environment
3. create crons, databases, users and config options






michiel

10-06-14 10:54

administrator   ~0053898

Sorry, maybe we should do what I suggest in a different issue.

This one, for setting up phpList on debian, yes, I think your vhost setting is fine

Maybe it's an idea to place the config file in /etc/ eg /etc/phplist-conf.php and then you can update the Vhost:

After DocumentRoot /var/www/phplist/public_html
Add:
---------
SetEnv ConfigFile /etc/phplist-conf.php
---------


But what is nice to add for a step is to set up phplist Commandline:


cd /usr/local/bin

cat << EOF > phplist
#!/bin/bash

/usr/bin/php /var/www/phplist/public_html/lists/admin/index.php -c /etc/phplist-conf.php $*
EOF

chmod 755 /usr/local/bin/phplist

and then write:

To process the queue run

phplist -pprocessqueue

to process bounces (provided that is set u, which could also become part of the installation procedure)

phplist -pprocessbounces

michiel

10-06-14 10:56

administrator   ~0053899

So, apart from web and mail (as mentioned in 0017208:0053896) there is effectively more to do:

bounce mailbox (+settings)
commandline
crons

rata

10-06-14 14:54

updater   ~0053903

Well, the instructions I gave cover what is said in the current documentation for installing phplist as documented here: http://docs.phplist.com/PhplistInstallation.html

Mail, commands and crons are not there, so they are not covered. Right now some of them at least seem to be in the "Post-install configuration" step in docs.phplist.com. Probably those could be improved too, but one step at a time.

My intent was to improve the http://docs.phplist.com/PhplistInstallation.html that some things, as what you need in the vhost or even how to create it, are not said there. So the user is much "on his own" to figure that out, and with an example it can be way more easy to do it. And it was easy for me to do it now, as I have just installed phplist.

Of course lot of other things can be improved and having a package for all distributions will make things even easier. But that needs probably several patches on phplist itself, as no external deps can be included, etc. (debian has pretty strict policies on that, also on location where certain files -as config files- should be placed) and it will take more time (and merging it into debian will take even more time). This could be done now, easily (took me some time to re-test the things and make sure it works, but still way less than doing a debian package) and I thought it improves the current situation.

But doing those seems like it would take more time, this one was a "low hanging fruit" now IMHO. I have no problem helping to improve the documentation, but I'd rather prefer to have a different issue for that. And I now wonder how should we coordinate with Anna any changes to the documentation, I totally forgot about that.

So, regarding the debian package IMHO should be another issue. And a really big one, as dependencies need to be changed to be handled differently, files should work if located on other paths, Makefile should be provided, etc. And only on the phplist side. Then a debian package should be done, with debconf interface to configure what is possible to do there, etc. And then we need to find a sponsor (a debian developer) who wants to review it, and when all changes needed are done, upload the package to Debian. We might also consider doing a debian package, not meant to be merged as-is, that does not satisfy all the strict debian policies and we can have our own mirror for that. So users can install "more easily" than now, although not yet in debian. And go "step by step". Is a possibility to consider. I think we should aim to get it on debian repos, but as a first step it might have some value to have our own repos. And a new issue seems a better way to analize all the possibilities (there are also some generic tools that creates packages for TONS of distros just doing some "simple" things. And those packages work but do not meet the standards debian has, so there are tons of things to consider)

What do you think ?

michiel

12-06-14 11:47

administrator   ~0053921


ok, let's keep this one a manual install, and work out the packaging in a different issue.

So, apart from the Vhost, there is:

1. commandline
2. bounce mailbox
3. crons


rata

12-06-14 15:47

updater   ~0053924

Re 1. Probably the best/easiest thing to do is add a "make install" that installs the commands. What do you think ?

Re 2. I've just read http://docs.phplist.com/PhpListConfigBounces.html and I find it pretty extensive and clear. Is there something not covered here or that can be improved ?

Re 3. The cron documentation was pretty clear for me. When I read it to help Caroline it was useful and clear, and help me solved the problem. What do you think is missing or can be improved ?

michiel

12-06-14 16:20

administrator   ~0053926


Ok, if all the info is there, then that's fine.

The old docs will be removed at some point though, so this should go into the new docs whenever possible.

gingerling

12-06-14 17:00

manager   ~0053928

yeps. It's on the list :D

gingerling

01-09-14 18:31

manager   ~0054782

also passed this over to guy who is writing that chapter