aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorpacien2020-09-19 06:26:28 +0200
committerpacien2020-09-19 23:31:29 +0200
commit7e8bba1a29da3341f7c173f17e19725e5822b5fc (patch)
treeca94737d09921011d5bc8f203e5bd3606fadfcdf
parent9a90abaeff9943118022e4cb71429db147ce7188 (diff)
downloadldgallery-7e8bba1a29da3341f7c173f17e19725e5822b5fc.tar.gz
docs: simplify quickstart guide
Remove the deploy step and focus on the other ones, providing tree examples.
-rw-r--r--ldgallery-quickstart.7.md79
1 files changed, 52 insertions, 27 deletions
diff --git a/ldgallery-quickstart.7.md b/ldgallery-quickstart.7.md
index c54e8f0..4c93f51 100644
--- a/ldgallery-quickstart.7.md
+++ b/ldgallery-quickstart.7.md
@@ -2,27 +2,41 @@
2pagetitle: Quickstart guide - ldgallery 2pagetitle: Quickstart guide - ldgallery
3title: LDGALLERY-QUICKSTART(7) ldgallery 3title: LDGALLERY-QUICKSTART(7) ldgallery
4author: Pacien TRAN-GIRARD, Guillaume FOUET 4author: Pacien TRAN-GIRARD, Guillaume FOUET
5date: 2020-05-01 (v1.0) 5date: 2020-09-19 (v2.0)
6--- 6---
7 7
8# ABOUT 8# ABOUT
9 9
10This document is a step-by-step guide showing how to create, compile and deploy a new gallery with _ldgallery_. 10This document is a step-by-step guide showing how to create and compile a simple gallery and get familiar with _ldgallery_.
11 11
12It mainly describes how to structure the source gallery directory accepted by the _ldgallery_ compiler.
12 13
13# QUICKSTART GUIDE 14```
15[source gallery directory with items and their tags]
16 |
17 | ldgallery compiler
18 v
19[generated web gallery with embedded web viewer]
20 |
21 | copy
22 v
23[web server]
24```
14 25
15## Step 1: setting up the compiler
16 26
17The _ldgallery_ compiler's job is to transform a directory containing pictures and other types of items, alongside additional metadata, into a gallery that can be viewed in a web browser. 27# QUICKSTART GUIDE
18 28
19This compiler program is typically installed and runs on the computer of the gallery's owner. 29## Step 1: initialising the gallery source directory
20 30
21It can be installed through a package manager (package name "ldgallery") or manually by extracting a prebuilt archive available on the project's website <https://ldgallery.pacien.org>. 31A new gallery can be initialised by creating a directory containing a gallery configuration file named __gallery.yaml__.
22 32
23## Step 2: initialising the gallery 33```
34./monument-gallery-source
35└── gallery.yaml ----------- gallery settings file
36```
24 37
25A minimal gallery can be initialised by creating a directory containing a gallery configuration file named "gallery.yaml" with the following content: 38__gallery.yaml__ holds the settings of the gallery.
39Its content can be as follows:
26 40
27```yaml 41```yaml
28# gallery.yaml: ldgallery example gallery configuration file. 42# gallery.yaml: ldgallery example gallery configuration file.
@@ -34,11 +48,20 @@ tagCategories:
34 - city 48 - city
35``` 49```
36 50
37## Step 3: adding items 51## Step 2: adding items
38 52
39A new item, say a picture file named "DSC0001.jpg", can now be added to the directory created at the previous step. 53A new item, say a picture file named "DSC0001.jpg", can now be added to the directory created at the previous step.
40 54
41Optionally, some metadata such as a title and some tags can be associated by creating a file named "DSC0001.jpg.yaml" at the same location, with the following content: 55Optionally, some metadata such as a title and some tags can be associated by creating a file named "DSC0001.jpg.yaml" at the same location.
56
57```
58./monument-gallery-source
59├── gallery.yaml ----------- gallery settings file
60├── DSC0001.jpg ------------ a picture
61└── DSC0001.jpg.yaml ------- its associated optional sidecar metadata file
62```
63
64The sidecar metadata file "DSC0001.jpg.yaml" can have the following content:
42 65
43```yaml 66```yaml
44# DSC0001.jpg.yaml: ldgallery metadata sidecar file for DSC0001.jpg. 67# DSC0001.jpg.yaml: ldgallery metadata sidecar file for DSC0001.jpg.
@@ -51,29 +74,29 @@ tags:
51 - tower 74 - tower
52``` 75```
53 76
54## Step 4: compiling the gallery 77## Step 3: compiling the gallery
55 78
56The gallery can now be compiled by running the following command in a terminal with the right path to the gallery directory created during the previous steps: 79The gallery can now be compiled by running the following command in a terminal with the right path to the gallery directory created during the previous steps:
57 80
58```sh 81```sh
59ldgallery --with-viewer --input-dir <source gallery path> 82ldgallery \
83 --with-viewer \
84 --input-dir ./monument-gallery-source \
85 --output-dir ./monument-gallery-output
60``` 86```
61 87
62If the compiler was installed manually through the extraction of a pre-built archive, it might be necessary to specify the full path of the installation: 88If the compiler was installed manually through the extraction of a pre-built archive,
89it might be necessary to specify the full path of the installation:
63 90
64```sh 91```sh
65<installation path>/ldgallery --with-viewer=<installation path>/viewer --input-dir <source gallery path> 92<installation path>/ldgallery \
93 --with-viewer=<installation path>/viewer \
94 --input-dir ./monument-gallery-source \
95 --output-dir ./monument-gallery-output
66``` 96```
67 97
68Running the command above produces a directory named "out" in the current directory, which contains the compiled gallery and a web viewer ready to be deployed on some web server. 98Running the command above produces a directory named "monument-gallery-output" in the current directory,
69 99which contains the compiled gallery and a web viewer ready to be copied to some web server.
70## Step 5: deploying the gallery
71
72The content of the "out" directory generated at the previous step can now simply be uploaded to some web host, for example with an FTP client like FileZilla or through rsync/SSH with the following command:
73
74```sh
75rsync -Prz out/* user@webhost:publication_path/
76```
77 100
78The target web host doesn't need to run any additional software besides a web server correctly configured to serve flat static files. 101The target web host doesn't need to run any additional software besides a web server correctly configured to serve flat static files.
79 102
@@ -82,18 +105,20 @@ The target web host doesn't need to run any additional software besides a web se
82 105
83## Version control 106## Version control
84 107
85Some standard version-control software such as Git or Mercurial can easily be used to keep track of the evolutions of the gallery directory, thanks to the text-based format used for the sidecar metadata files. 108Some standard version-control software such as Git or Mercurial can easily be used to keep track of the evolutions of the gallery directory,
109thanks to the text-based format used for the sidecar metadata files.
86 110
87## Automated compilation and deployment 111## Automated compilation and deployment
88 112
89The compilation and upload commands can be combined in a Makefile or made part of a script for faster and more convenient deployments. 113The gallery can quickly be deployed by using a command such as `rsync`.
90 114
115The compilation and upload commands can be combined in a Makefile or made part of a script for faster and more convenient deployments.
91Such scripted procedure can then further be automated through Continuous Integration hooks. 116Such scripted procedure can then further be automated through Continuous Integration hooks.
92 117
93 118
94# SEE ALSO 119# SEE ALSO
95 120
96Related manual pages: __ldgallery__(1), __ldgallery-viewer__(7) 121Related manual pages: __ldgallery__(1), __ldgallery-viewer__(7).
97 122
98The ldgallery source code is available on <https://ldgallery.pacien.org>. 123The ldgallery source code is available on <https://ldgallery.pacien.org>.
99 124