eidolon/README.md

225 lines
6.4 KiB
Markdown
Raw Normal View History

2017-03-10 18:01:09 +00:00
# eidolon
2014-08-09 18:31:58 +00:00
2017-03-10 18:01:09 +00:00
## Introduction
2014-12-26 22:38:25 +00:00
2015-03-28 03:20:29 +00:00
A image gallery service written in Haskell as a yesod webapp.
2014-12-26 22:38:25 +00:00
2015-03-28 03:20:29 +00:00
Visit the test instance at [eidolon.nek0.eu][eidolon]
2015-01-11 17:04:55 +00:00
2017-03-10 18:01:09 +00:00
## Installation
2014-12-26 22:38:25 +00:00
2017-03-10 18:01:09 +00:00
### Dependencies
2014-12-26 22:38:25 +00:00
2017-03-10 18:01:09 +00:00
#### Build dependencies
2015-10-18 02:33:02 +00:00
2016-12-03 20:53:39 +00:00
A working Haskell capable environment. For that you will need `ghc` and
`cabal-install`, which you can install with:
2014-12-26 22:38:25 +00:00
2015-10-14 22:53:22 +00:00
```bash
2016-12-03 20:53:39 +00:00
sudo apt-get install ghc cabal-install
2015-10-14 22:53:22 +00:00
```
2016-09-06 14:47:43 +00:00
Now you can set up your cabal with `cabal update` and follow its instructions.
2017-11-01 23:40:56 +00:00
With this you will have also installed the latest GHC Haskell compiler on your
2016-09-06 14:47:43 +00:00
system.
2015-10-14 22:53:22 +00:00
2016-07-22 16:23:59 +00:00
Additionally to Haskell and its dependencies you will need the following
software and libraries:
2014-12-26 22:38:25 +00:00
* alex
* happy
2018-03-18 22:40:14 +00:00
* unzip
2016-01-05 01:26:20 +00:00
* libpq-dev
* postgresql
2016-05-08 22:09:39 +00:00
* libfftw3-dev
2016-12-03 15:42:22 +00:00
* npm
2016-12-03 16:16:13 +00:00
* nodejs-legacy
2017-10-31 09:01:26 +00:00
* libpoppler-glib-dev
* libcairo2-dev
2017-10-31 09:15:58 +00:00
* libgtk2.0-dev
2018-03-18 22:35:31 +00:00
* libmagic-dev
2014-12-26 22:38:25 +00:00
2017-11-01 23:40:56 +00:00
Which can be installed through
2015-10-14 22:53:22 +00:00
```bash
2018-03-18 22:40:14 +00:00
sudo apt-get install alex happy unzip libpq-dev postgresql npm nodejs-legacy libpoppler-glib-dev libcairo2-dev libgtk2.0-dev libfftw3-dev libmagic-dev
2016-12-03 15:42:22 +00:00
```
2016-12-03 16:16:13 +00:00
Additionally you need bower, purescript and pulp:
2016-12-03 15:42:22 +00:00
```bash
npm install -g bower
2016-12-03 16:16:13 +00:00
npm install -g purescript
npm install -g pulp
2015-10-14 22:53:22 +00:00
```
2017-11-01 23:40:56 +00:00
For migrations also install:
2016-11-20 06:50:23 +00:00
* libmagic-dev
2017-03-10 18:01:09 +00:00
#### Elasticsearch dependencies
2015-10-18 02:33:02 +00:00
2016-09-06 14:47:43 +00:00
**WARNING: THIS SECTION IS ONLY VALID FOR VERSIONS >= 0.0.5 and < 0.1.0.0**
2016-07-22 16:23:59 +00:00
Since version 0.0.5 there is an Elasticsearch integration for Eidolon. To Be
able to run eidolon , you need to install `elasticsearch` additionally with:
2015-10-18 02:33:02 +00:00
```bash
sudo apt-get install elasticsearch
```
2016-07-22 16:23:59 +00:00
On how to configure your elasticsearch server, look into the
[elasticsearch documentation][elasticdocu].
2015-10-18 02:33:02 +00:00
2017-03-10 18:01:09 +00:00
### Building
2014-12-26 22:38:25 +00:00
2017-11-01 23:40:56 +00:00
Get the source with
2014-12-26 22:38:25 +00:00
```bash
git clone https://github.com/nek0/eidolon.git
```
2017-11-01 23:40:56 +00:00
Build your sandbox with
2016-09-06 14:47:43 +00:00
```bash
cabal sandbox init
```
2017-11-01 23:40:56 +00:00
Build the source with
2014-12-26 22:38:25 +00:00
```bash
2016-12-03 15:42:22 +00:00
make all
2014-12-26 22:38:25 +00:00
```
2016-07-22 16:23:59 +00:00
Everything should work automagically from there.
2017-03-10 18:01:09 +00:00
## Deploying
2014-12-26 22:38:25 +00:00
2017-11-01 23:40:56 +00:00
First you need to set up your database, which just needs to be created.
2017-10-20 17:05:30 +00:00
Additionally you connect to your database (with `psql` or similar) and activate
the `pg_trgm` extension to the database with
```sql
CREATE EXTENSION pg_trgm;
```
2016-03-02 13:59:28 +00:00
After compiling you will find an executable called `eidolon` in
2016-09-06 15:30:41 +00:00
`dist/build/eidolon/eidolon`. Copy or link it anywhere you
2016-09-06 14:47:43 +00:00
want. The executable needs to be accompanied by the folders `config` and
`static` and their contents. It's best to copy them to your desired destination.
2014-12-26 22:38:25 +00:00
2017-11-01 23:40:56 +00:00
Also check `config/settings.yml` and set the values there according to your
2016-09-09 19:41:22 +00:00
configuration. The field `contactEmail` is optional, you can comment it out, but
be aware. In certain jurisdictions you are required to give some contact
information.
2014-12-26 22:38:25 +00:00
2017-11-01 23:40:56 +00:00
It may also be necessary to create a reverse proxy to your gallery. I would
2016-07-22 16:23:59 +00:00
recommend using [nginx](http://nginx.org/).
2014-12-26 22:38:25 +00:00
2017-03-10 18:01:09 +00:00
## Customizing
2015-01-18 01:55:49 +00:00
2016-07-22 16:23:59 +00:00
Unfortunately the gallery is not highly customizable, but you can change most of
2016-09-06 14:47:43 +00:00
its appearance by changing the files `static/css/main.css`. Especially the
2016-07-22 16:23:59 +00:00
default background image can be changed by replacing `static/css/img/bg.jpg`.
2015-01-18 01:55:49 +00:00
2017-03-10 18:01:09 +00:00
## Starting
2014-12-26 22:38:25 +00:00
2016-07-22 16:23:59 +00:00
You can start the gallery now by running the executable. You need to provide a
settings file as argument, normally found in `config/settings.yml`
2014-12-26 22:38:25 +00:00
2016-07-22 16:23:59 +00:00
Since eidolon will block your console, I recommend wrapping a init-script around
it. how you can do that is written in my
[blog](http://nek0.eu/posts/2014-10-23-Daemonize-a-yesod-app.html).
2015-01-18 19:44:41 +00:00
2017-03-10 18:01:09 +00:00
## Migrations
2017-03-10 18:01:09 +00:00
### 0.0.3-0.0.4
* do not start or restart your eidolon service before migration
2016-07-22 16:23:59 +00:00
* run migration script from your run location (where your `static` folder with
all the images is located)
2016-03-02 13:59:28 +00:00
* if you are building in a sandbox run
`runghc -package-db/full/path/to/sandbox/XXX-ghc-version-packages.conf.d
/path/to/eidolon/Migrations/0.0.3-0.0.4/Migration.hs`
2015-09-28 17:58:49 +00:00
* Note: No space between the option `-package-db` and its argument
* without sandbox: `runghc /path/to/eidolon/Migrations/0.0.3-0.0.4/Migration.hs`
* start or restart your eidolon service
2017-03-10 18:01:09 +00:00
### 0.0.4-0.0.5
2015-10-18 02:33:02 +00:00
2016-07-22 16:23:59 +00:00
* run migration script from your run location (where your `static` folder with
all the images is located)
2016-03-02 13:59:28 +00:00
* if you are building in a sandbox run `runghc
-package-db/full/path/to/sandbox/XXX-ghc-version-packages.conf.d
/path/to/eidolon/Migrations/0.0.4-0.0.5/Migration.hs`
2015-10-18 02:33:02 +00:00
* Note: No space between the option `-package-db` and its argument
* without sandbox: `runghc /path/to/eidolon/Migrations/0.0.4-0.0.5/Migration.hs`
* start or restart your eidolon service
2017-03-10 18:01:09 +00:00
### 0.0.7-0.1.0.0
2016-09-06 14:47:43 +00:00
You have two options to accomplish the migration:
1. Build the migration binary with `cabal exec -- ghc --make
Migrations/0.0.7-0.1.0.0/Migration.hs` and run the executable in your run
location.
2. Link the `static/data/` folder from your link location in the same location
in the project directory and run `cabal exec -- runghc
Migrations/0.0.7-0.1.0.0/Migration.hs`
2017-03-10 18:01:09 +00:00
### 0.1.2.4-0.1.3.0
* Stop Eidolon
* Log into your database and issue this command:
`ALTER TABLE "comment" DROP COLUMN "author_slug";`
* Start Eidolon
2017-03-10 18:01:09 +00:00
### 0.1.3.3-0.1.4.0
2016-11-20 06:50:23 +00:00
* Stop eidolon
* Compile migration script with `cabal exec -- ghc --make Migrations/0.1.3.3-0.1.4.0/Migration.hs`
* Copy or move compiled script to run location and execute
* Follow the prompts of the script
* Start eidolon
2017-03-10 18:01:09 +00:00
### 0.1.4.0-0.1.5.0
2016-12-03 15:42:22 +00:00
* Stop eidolon
* Compile migration script with `cabal exec -- ghc --make Migrations/0.1.4.0-0.1.5.0/Migration.hs`
* Copy or move compiled script to run location and execute
* Follow the prompts of the script
* Start eidolon
2017-03-10 18:01:09 +00:00
### 0.1.5.6-0.1.6.0
2016-12-19 00:48:35 +00:00
* Just restart eidolon. It handles the rest automagically.
2017-03-10 18:01:09 +00:00
### 0.1.6.1-0.1.7.0
2016-12-19 02:21:27 +00:00
* No database changes. Just restart eidolon.
2017-03-10 18:01:09 +00:00
### 0.1.7.2-0.1.8.0
2017-01-06 19:29:28 +00:00
* No database changes, just new dependencies to install.
2017-04-26 19:59:45 +00:00
### 0.1.8.8-0.1.9.0
2017-04-26 20:34:42 +00:00
* Run `ALTER TABLE "token" DROP COLUMN "user";` and `truncate token;`
from your postgres console.
2017-04-26 19:59:45 +00:00
* You can drop the table `activator` from the database. It is no longer needed.
2017-08-08 07:41:12 +00:00
### 0.1.9.3-0.1.10.0
* Nothing to do, just internal changes.
2017-08-13 21:06:39 +00:00
### 0.1.10.0-0.1.11.0
* Only new dependencies to install. You might also want to check out the new
function to repopulate the thumbnail images, if you have some of them corrupted
by unhandled EXIF data.
2017-10-20 17:08:55 +00:00
### 0.1.11.2-0.1.11.3
* Activate the `pg_trgm` extension for your database with
`CREATE EXTENSION pg_trgm;`.
2017-03-10 18:01:09 +00:00
## Acknowledgements:
2015-01-18 19:44:41 +00:00
2016-03-02 13:59:28 +00:00
* This software uses the web Framework "Yesod" by Michael Snoyman. See more at:
<http://www.yesodweb.com/>
2015-01-18 19:44:41 +00:00
2015-03-28 03:20:29 +00:00
[eidolon]: http://eidolon.nek0.eu
2015-10-14 22:53:22 +00:00
[stack]: https://github.com/commercialhaskell/stack/releases
2015-10-18 02:33:02 +00:00
[elasticdocu]: https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-configuration.html