If you are just looking to give Agorakit a try, you can do that without having to install it. Just create an account on https://app.agorakit.org, where you can try an Agorakit instance free for citizen-activists and for evaluation purposes.
You can also get in touch with us if you are interested in managed hosting of a private Agorakit instance. Email us at info [at] agorakit.org for more details.
Keep reading for steps to install an Agorakit instance on your own server.
You need a good web hosting provider that provides the following :
- php >= 7.1.3 with the following extensions :
- OpenSSL PHP Extension
- PDO PHP Extension
- Mbstring PHP Extension
- Tokenizer PHP Extension
- XML PHP Extension
- Ctype PHP Extension
- JSON PHP Extension
- BCMath PHP Extension
- Mysql or MariaDb
- the ability to run cron jobs
All those features together are hard to find, so people are obliged to use a VPS and setup everything themselves. This is a riskier proposal if you don’t know how it works.
Currently, you need to know how to install a Laravel application using the command line. This is perfectly standard and documented here : https://laravel.com/docs/master/installation.
Clone the repository:
$ git clone https://github.com/philippejadin/agorakit.git
Create and edit the configuration file from the example provided:
$ cp .env.example .env $ nano .env
You need to set at least your database credentials & site name. Check that your database exists and is reachable with those credentials.
Here is a description of every setting in the .env file:
APP_ENV=local // local or production APP_DEBUG=true // show the debugbar and extended errors or not APP_KEY=SomeRandomString // will be auto generated APP_NAME='Agorakit' // name of your application APP_URL=http://locahost // base url APP_LOG=daily // log rotation APP_DEFAULT_LOCALE=en // default locale when not detected from user browser DB_HOST=localhost // host of your mysql server DB_DATABASE=agorakit // db name of your sql DB DB_USERNAME=root // login of mysql DB_PASSWORD= // password of mysql CACHE_DRIVER=file // driver to use for caching SESSION_DRIVER=file // driver to use for storing sessions QUEUE_DRIVER=sync // driver to use for queues MAIL_DRIVER=smtp // driver to use for sending emails. Use mail to use php built-in mail function MAIL_HOST=mailtrap.io // hostname if you use smtp for sending mails MAIL_PORT=2525 // port if you use smtp for sending mails MAIL_USERNAME=null // login if you use smtp for sending mails MAIL_PASSWORD=null // password if you use smtp for sending mails MAIL_ENCRYPTION=null // encryption if you use smtp for sending mails MAIL_FROM=admin@localhost // from email adress used when sending admin emails MAIL_FROM_NAME=Agorakit // name of sender of admin emails MAIL_NOREPLY=noreply@localhost // no reply adress for service messages MAPBOX_TOKEN=null // Create a Mapbox account and generate a token to enable geolocalisation and display maps
Download all the packages needed:
$ composer install
Generate a key:
$ php artisan key:generate
Migrate (create all tables in) the database:
$ php artisan migrate Link the storage public folder to the user visible public folder:: $ php artisan storage:link
(Optional) Create sample content the database:
$ php artisan db:seed
Don’t do this last step for a production install since it will create an admin user and dummy groups and content.
Setup your web server¶
Then setup your web server to serve the /public directory. This is very important, since you don’t want to expose the rest of the directories (for example you DON’T want to expose your .env file!)
Setup a cron job¶
Follow Laravel cron documentation here : https://laravel.com/docs/master/scheduling The cron jobs are used to send group summaries at a fixed interval, for the inbound email handler and for various database interactions.
Setup geolocalisation and mapping¶
Create an account at Mapbox.com and create an api token. Then fill this api token in your .env file. With this, you will get geocoding and maps. We switched from Google maps to Mapbox because Google Maps now requires a credit card even for the free tier. Mapbox free tier is probably enough for your use (50k displays / month at the time of writing)
Setup inbound emails¶
This additional step allows you to have one mailbox for each group so members can post by email.
You need an email address on server with imap. It must either be a catch all on a subdomain (or even on a domain) or a server supporting “+” addressing (gmail for example allows this).
Let’s say you installed Agorakit on agora.example.org Create a catchall mailbox on *.@agora.example.org
Then go to admin settings and fill the form there (end of the page).
You need to fill server & login & password
Then you need to fill prefix and suffix. Two cases there :
For a catch all there is no prefix. The suffix in the above example would be @agora.example.org . This will create emails like email@example.com
On the other hand if you use “+” addressing (a gmail box for instance, let’s call it firstname.lastname@example.org),
- prefix will be agorakit+
- suffix will be @gmail.com
Wich create emails like email@example.com
If you enable inbound email, the mailbox will be automatically checked and processed email will be put in a “processed” folder under INBOX. Failed emails will be similarly put a “Failed” folder under INBOX for inspection.