eidolon/README.md

194 lines
5.5 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.
with this you will have also installed the latest GHC Haskell compiler on your
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
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
2014-12-26 22:38:25 +00:00
2015-10-14 22:53:22 +00:00
which can be installed through
```bash
2016-12-03 16:16:13 +00:00
sudo apt-get install alex happy libpq-dev postgresql npm nodejs-legacy
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
```
2016-11-20 06:50:23 +00:00
for migrations also install:
* 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
get the source with
```bash
git clone https://github.com/nek0/eidolon.git
```
2016-09-06 14:47:43 +00:00
build your sandbox with
```bash
cabal sandbox init
```
2016-01-05 00:57:32 +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
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
2016-07-22 16:23:59 +00:00
Also check `config/settings.yml` and set the values there accrding 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
2016-07-22 16:23:59 +00:00
It may also be necessery to create a reverse proxy to your gallery. I would
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-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
* This software uses parts of the template "Parallelism" by n33co. see more at: <http://html5up.net/>
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