eidolon/README.md

188 lines
5.4 KiB
Markdown
Raw Normal View History

2014-08-09 18:31:58 +00:00
#eidolon
2014-12-26 22:38:25 +00:00
##Introduction
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
2014-12-26 22:38:25 +00:00
##Installation
###Dependencies
2015-10-18 02:33:02 +00:00
####Build dependencies
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
2015-10-18 02:33:02 +00:00
####Elasticsearch dependencies
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
2014-12-26 22:38:25 +00:00
###Building
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.
2014-12-26 22:38:25 +00:00
##Deploying
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
2015-01-18 01:55:49 +00:00
##Customizing
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
2014-12-26 22:38:25 +00:00
##Starting
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
##Migrations
###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
2015-10-18 02:33:02 +00:00
###0.0.4-0.0.5
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
2016-09-06 14:47:43 +00:00
###0.0.7-0.1.0.0
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`
###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
2016-11-20 06:50:23 +00:00
###0.1.3.3-0.1.4.0
* 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
2016-12-03 15:42:22 +00:00
###0.1.4.0-0.1.5.0
* 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
2016-12-19 00:48:35 +00:00
###0.1.5.6-0.1.6.0
* Just restart eidolon. It handles the rest automagically.
2015-01-18 19:44:41 +00:00
##Acknowledgements:
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