Merge pull request #25 from appunite/installation-docs

docs: document installation and configuration

.tool-versions

@@ -1,2 +1,2 @@
-elixir 1.7.2
-erlang 20.2
+elixir 1.7.3
+erlang 21.1

Dockerfile

@@ -21,10 +21,13 @@ RUN apk add --update \
     && rm -rf /var/cache/apk/*
 ENV MIX_ENV prod
 ENV OPTIMIZE true
-COPY . /app
+RUN mkdir /app
+COPY mix.exs /app
+COPY mix.lock /app
 WORKDIR /app
 RUN mix do local.hex --force, local.rebar --force
 RUN mix do deps.get, deps.compile
+COPY . /app
 RUN mix do compile, release --env=prod
 
 FROM source

README.md

@@ -43,14 +43,47 @@ only ImageMagick.
 
 ## Installation
 
-TBD
+### Docker
+
+Currently the only officially supported installation way is via official Docker
+image that can be found on [Docker Hub][hub].
+
+1. First we need to generate configuration file for Imager
+
+  ```
+  $ docker run --rm appunite/imager:latest config > config.toml
+  ```
+
+1. Edit `config.toml`.  Documentation is available within the file itself.
+1. Run container providing configuration.
+
+  ```
+  $ docker run --rm -v './config.toml:/etc/imager/config.toml:ro' -p 8080:80 appunite/imager:latest
+  ```
 
 ## Usage
 
-TBD
+Assuming that you have store named `local` and there is file named `lenna.png`
+you can access this file directly via on <http://localhost:8080/local/lenna.png>,
+to generate thumbnail of size `50x50` pixels you can then use
+<http://localhost:8080/local/lenna.png?thumbnail=50x50>.
+
+Currently available options are:
+
+- `thumbnail=<size>`
+- `strip`
+- `gravity=<gravity>`
+- `extent=<size>`
+- `flatten`
+- `background=<colour>`
+- `format=<format>`
+
+Which maps 1:1 to their respective [ImageMagick flags][im-flags].
 
 ## License
 
 See [LICENSE](LICENSE) file.
 
+[im-flags]: https://imagemagick.org/script/command-line-processing.php#option
 [DICOM]: https://en.wikipedia.org/wiki/DICOM "DICOM - Wikipedia"
+[hub]: https://hub.docker.com/r/appunite/imager/ "appunite/imager - Docker Hub"

lib/imager/config.ex

@@ -26,6 +26,9 @@ defmodule Imager.Config do
     end
   end
 
+  def example,
+    do: IO.puts(File.read!(Path.join(:code.priv_dir(:imager), "config.toml")))
+
   defp persist(map) when is_map(map) do
     for {key, values} <- map do
       values = deep_merge(Application.get_env(:imager, key), values)

priv/config.toml.template → priv/config.toml

@@ -1,6 +1,6 @@
 # # General configuration
 #
-# Port to listen on
+# Port to listen on (do not use in Docker installations)
 # port = "$PORT"
 #
 # Key used to sign tokens used to verify requests.
@@ -14,7 +14,7 @@
 # Each store is defined in form
 #
 #       [stores.<path>]
-#       type = "S3" or "Local" # case sensitive
+#       type = "Local" # case sensitive
 #
 # Each store can also be provided with additional options in form
 #
@@ -42,9 +42,11 @@
 # There is no way to cast given variable to different type
 
 # # Store types
-#
+
 # ## S3
 #
+# Store that uses S3-compatible service as a remote store.
+#
 # Available options:
 # `bucket` (required) - bucket name for given storage
 # `region` (required) - AWS storage region
@@ -63,3 +65,25 @@
 #     scheme = "$S3_SCHEME"
 #     port = "$S3_PORT"
 #     region = "eu-west-1"
+
+# ## Local
+#
+# Store that uses local directory.
+#
+# Available options:
+# `dir` (required) - directory where images are/will be stored
+
+# [stores.local]
+# type = "Local"
+#     [stores.local.options]
+#     dir = "/var/imager"
+
+# ## Blackhole
+#
+# Store that discards all writes and always fail on read.
+#
+# Can be useful when using CDN and we do not want to store images at all and
+# rely on extrnal caching system.
+
+# [stores.dump]
+# type = "Blackhole"

rel/commands/config.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+release_ctl eval --mfa 'Imager.Config.example/0'

rel/config.exs

@@ -13,6 +13,9 @@ use Mix.Releases.Config,
     default_environment: Mix.env()
 
 environment :prod do
+  set commands: [
+    config: "rel/commands/config.sh"
+  ]
   set include_erts: true
   set include_src: false
   set cookie: :"1u[<S!I(rduF/Rzy8)&A<,$D{;y:&av9?V],2S/37FKidw5JKpq|j17^D2Gz]N=m"
@@ -21,9 +24,6 @@ environment :prod do
     {Imager.Config, path: "${RELEASE_ROOT_DIR}/etc/imager/config.toml"},
     {Imager.Config, path: "${IMAGER_CONFIG}"},
   ]
-  set overlays: [
-    {:copy, "priv/config.toml.template", "etc/imager/config.toml"}
-  ]
 end
 
 # You may define one or more releases in this file.