aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Docker.md158
-rw-r--r--doc/REST-API.md105
-rw-r--r--doc/Versioning-and-Branches.md76
-rw-r--r--doc/_Sidebar.md39
-rw-r--r--doc/md/docker/docker-101.md (renamed from doc/md/Docker-101.md)0
-rw-r--r--doc/md/docker/resources.md (renamed from doc/md/Docker-resources.md)0
-rw-r--r--doc/md/docker/reverse-proxy-configuration.md (renamed from doc/md/Reverse-proxy-configuration.md)0
-rw-r--r--doc/md/docker/shaarli-images.md (renamed from doc/md/Shaarli-images.md)1
8 files changed, 0 insertions, 379 deletions
diff --git a/doc/Docker.md b/doc/Docker.md
deleted file mode 100644
index a7d2efb5..00000000
--- a/doc/Docker.md
+++ /dev/null
@@ -1,158 +0,0 @@
1#Docker
2- [Docker usage](#docker-usage)[](.html)
3- [Get and run a Shaarli image](#get-and-run-a-shaarli-image)[](.html)
4- [Resources](#resources)[](.html)
5
6## Docker usage
7### Basics
8Install [Docker](https://www.docker.com/), by following the instructions relevant[](.html)
9to your OS / distribution, and start the service.
10
11#### Search an image on [DockerHub](https://hub.docker.com/)[](.html)
12
13```bash
14$ docker search debian
15
16NAME DESCRIPTION STARS OFFICIAL AUTOMATED
17ubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK][](.html)
18debian Debian is a Linux distribution that's comp... 603 [OK][](.html)
19google/debian 47 [OK][](.html)
20```
21
22#### Show available tags for a repository
23```bash
24$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool
25
26% Total % Received % Xferd Average Speed Time Time Time Current
27Dload Upload Total Spent Left Speed
28100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433
29```
30
31Sample output:
32```json
33[[](.html)
34 {
35 "layer": "85a02782",
36 "name": "stretch"
37 },
38 {
39 "layer": "59abecbc",
40 "name": "testing"
41 },
42 {
43 "layer": "bf0fd686",
44 "name": "unstable"
45 },
46 {
47 "layer": "60c52dbe",
48 "name": "wheezy"
49 },
50 {
51 "layer": "c5b806fe",
52 "name": "wheezy-backports"
53 }
54]
55
56```
57
58#### Pull an image from DockerHub
59```bash
60$ docker pull repository[:tag][](.html)
61
62$ docker pull debian:wheezy
63wheezy: Pulling from debian
644c8cbfd2973e: Pull complete
6560c52dbe9d91: Pull complete
66Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe
67Status: Downloaded newer image for debian:wheezy
68```
69
70## Get and run a Shaarli image
71### DockerHub repository
72The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaarli/shaarli/)[](.html)
73repository.
74
75### Available image tags
76- `latest`: master branch (tarball release)
77- `stable`: stable branch (tarball release)
78- `dev`: master branch (Git clone)
79
80All images rely on:
81- [Debian 8 Jessie](https://hub.docker.com/_/debian/)[](.html)
82- [PHP5-FPM](http://php-fpm.org/)[](.html)
83- [Nginx](http://nginx.org/)[](.html)
84
85### Download from DockerHub
86```bash
87$ docker pull shaarli/shaarli
88latest: Pulling from shaarli/shaarli
8932716d9fcddb: Pull complete
9084899d045435: Pull complete
914b6ad7444763: Pull complete
92e0345ef7a3e0: Pull complete
935c1dd344094f: Pull complete
946422305a200b: Pull complete
957d63f861dbef: Pull complete
963eb97210645c: Pull complete
97869319d746ff: Already exists
98869319d746ff: Pulling fs layer
99902b87aaaec9: Already exists
100Digest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98
101Status: Downloaded newer image for shaarli/shaarli:latest
102```
103
104### Create and start a new container from the image
105```bash
106# map the host's :8000 port to the container's :80 port
107$ docker create -p 8000:80 shaarli/shaarli
108d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
109
110# launch the container in the background
111$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
112d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
113
114# list active containers
115$ docker ps
116CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
117d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo
118```
119
120### Stop and destroy a container
121```bash
122$ docker stop backstabbing_galileo # those docker guys are really rude to physicists!
123backstabbing_galileo
124
125# check the container is stopped
126$ docker ps
127CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
128
129# list ALL containers
130$ docker ps -a
131CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
132d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo
133
134# destroy the container
135$ docker rm backstabbing_galileo # let's put an end to these barbarian practices
136backstabbing_galileo
137
138$ docker ps -a
139CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
140```
141
142## Resources
143### Docker
144- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/)[](.html)
145- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/)[](.html)
146- [Dockerfile reference](https://docs.docker.com/reference/builder/)[](.html)
147- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)[](.html)
148- [Volumes](https://docs.docker.com/userguide/dockervolumes/)[](.html)
149
150### DockerHub
151- [Repositories](https://docs.docker.com/userguide/dockerrepos/)[](.html)
152- [Teams and organizations](https://docs.docker.com/docker-hub/orgs/)[](.html)
153- [GitHub automated build](https://docs.docker.com/docker-hub/github/)[](.html)
154
155### Service management
156- [Using supervisord](https://docs.docker.com/articles/using_supervisord/)[](.html)
157- [Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon)[](.html)
158- [supervisord](http://supervisord.org/)[](.html)
diff --git a/doc/REST-API.md b/doc/REST-API.md
deleted file mode 100644
index d7909978..00000000
--- a/doc/REST-API.md
+++ /dev/null
@@ -1,105 +0,0 @@
1#REST API
2## Usage
3
4See the [REST API documentation](http://shaarli.github.io/api-documentation/).[](.html)
5
6## Authentication
7
8All requests to Shaarli's API must include a JWT token to verify their authenticity.
9
10This token has to be included as an HTTP header called `Authentication: Bearer <jwt token>`.
11
12JWT resources :
13
14 * [jwt.io](https://jwt.io) (including a list of client per language).[](.html)
15 * RFC : https://tools.ietf.org/html/rfc7519
16 * https://float-middle.com/json-web-tokens-jwt-vs-sessions/
17 * HackerNews thread: https://news.ycombinator.com/item?id=11929267
18
19
20### Shaarli JWT Token
21
22JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64:
23
24```
25[header].[payload].[signature][](.html)
26```
27
28#### Header
29
30Shaarli only allow one hash algorithm, so the header will always be the same:
31
32```json
33{
34 "typ": "JWT",
35 "alg": "HS512"
36}
37```
38
39Encoded in base64, it gives:
40
41```
42ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
43```
44
45#### Payload
46
47**Validity duration**
48
49To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key `iat` (issued at). This token will be accepted during 9 minutes.
50
51```json
52{
53 "iat": 1468663519
54}
55```
56
57See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6).[](.html)
58
59
60#### Signature
61
62The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page.
63
64Signature example with PHP:
65
66```php
67$content = base64_encode($header) . '.' . base64_encode($payload);
68$signature = hash_hmac('sha512', $content, $secret);
69```
70
71
72### Complete example
73
74#### PHP
75
76```php
77function generateToken($secret) {
78 $header = base64_encode('{
79 "typ": "JWT",
80 "alg": "HS512"
81 }');
82 $payload = base64_encode('{
83 "iat": '. time() .'
84 }');
85 $signature = hash_hmac('sha512', $header .'.'. $payload , $secret);
86 return $header .'.'. $payload .'.'. $signature;
87}
88
89$secret = 'mysecret';
90$token = generateToken($secret);
91echo $token;
92```
93
94> `ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68`
95
96```php
97$options = [[](.html)
98 'http' => [[](.html)
99 'method' => 'GET',
100 'jwt' => $token,
101 ],
102];
103$context = stream_context_create($options);
104file_get_contents($apiEndpoint, false, $context);
105```
diff --git a/doc/Versioning-and-Branches.md b/doc/Versioning-and-Branches.md
deleted file mode 100644
index bbc7719e..00000000
--- a/doc/Versioning-and-Branches.md
+++ /dev/null
@@ -1,76 +0,0 @@
1#Versioning and Branches
2[**WORK IN PROGRESS**][](.html)
3
4It's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible.
5
6## `master` branch
7
8The `master` branch is the development branch. Any new change MUST go through this branch using Pull Requests.
9
10Remarks:
11
12 * This branch shouldn't be used for production as it isn't necessary stable.
13 * 3rd party aren't required to be compatible with the latest changes.
14 * Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
15 * The version in this branch is always `dev`.
16
17## `v0.x` branch
18
19This `v0.x` branch, points to the latest `v0.x.y` release.
20
21Explanation:
22
23When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.
24
25In this case, the issue is fixed in the `master` branch, and the fix is backported the to the `v0.x` branch. Then a new release is made from the `v0.x` branch.
26
27This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.
28
29## `latest` branch
30
31This branch point the latest release. It recommended to use it to get the latest tested changes.
32
33## `stable` branch
34
35The `stable` branch doesn't contain any major bug, and is one major digit version behind the latest release.
36
37For example, the current latest release is `v0.8.3`, the stable branch is an alias to the latest `v0.7.x` release. When the `v0.9.0` version will be released, the stable will move to the latest `v0.8.x` release.
38
39Remarks:
40
41 * Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
42
43## Releases
44
45Releases are always made from the latest `v0.x` branch.
46
47Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.
48
49## Advices on 3rd party git repos workflow
50
51### Versioning
52
53Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the [changelog](https://github.com/shaarli/Shaarli/releases) (*Draft* means not released yet) and the commit log (like [`tpl` folder](https://github.com/shaarli/Shaarli/commits/master/tpl/default) for themes)). You can either:[](.html)
54
55 - use the Shaarli version number, with your repo version. For example, if Shaarli `v0.8.3` is released, publish a `v0.8.3-1` release, where `v0.8.3` states Shaarli compatibility and `-1` is your own version digit for the current Shaarli version.
56 - use your own versioning scheme, and state Shaarli compatibility in the release description.
57
58Using this, any user will be able to pick the release matching his own Shaarli version.
59
60### Major bugfix backport releases
61
62To be able to support backported fixes, it recommended to use our workflow:
63
64```bash
65# In master, fix the major bug
66git commit -m "Katastrophe"
67git push origin master
68# Get your commit hash
69git log --format="%H" -n 1
70# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)
71git checkout -b katastrophe v0.8.2-1
72# Backport the fix commit to your brand new branch
73git cherry-pick <fix commit hash>
74git push origin katastrophe
75# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
76```
diff --git a/doc/_Sidebar.md b/doc/_Sidebar.md
deleted file mode 100644
index 8df2e565..00000000
--- a/doc/_Sidebar.md
+++ /dev/null
@@ -1,39 +0,0 @@
1#_Sidebar
2- [Home](Home.html)
3- Setup
4 - [Download and Installation](Download-and-Installation.html)
5 - [Upgrade and migration](Upgrade-and-migration.html)
6 - [Server requirements](Server-requirements.html)
7 - [Server configuration](Server-configuration.html)
8 - [Server security](Server-security.html)
9 - [Shaarli configuration](Shaarli-configuration.html)
10 - [Plugins](Plugins.html)
11- [Docker](Docker.html)
12- [Usage](Usage.html)
13 - [Sharing button](Sharing-button.html) (bookmarklet)
14 - [Browsing and Searching](Browsing-and-Searching.html)
15 - [Firefox share](Firefox-share.html)
16 - [RSS feeds](RSS-feeds.html)
17 - [REST API](REST-API.html)
18- How To
19 - [Backup, restore, import and export](Backup,-restore,-import-and-export.html)
20 - [Copy an existing installation over SSH and serve it locally](Copy-an-existing-installation-over-SSH-and-serve-it-locally.html)
21 - [Create and serve multiple Shaarlis (farm)](Create-and-serve-multiple-Shaarlis-(farm).html)
22 - [Download CSS styles from an OPML list](Download-CSS-styles-from-an-OPML-list.html)
23 - [Datastore hacks](Datastore-hacks.html)
24- [Troubleshooting](Troubleshooting.html)
25- [Development](Development.html)
26 - [GnuPG signature](GnuPG-signature.html)
27 - [Coding guidelines](Coding-guidelines.html)
28 - [Directory structure](Directory-structure.html)
29 - [3rd party libraries](3rd-party-libraries.html)
30 - [Plugin System](Plugin-System.html)
31 - [Release Shaarli](Release-Shaarli.html)
32 - [Versioning and Branches](Versioning-and-Branches.html)
33 - [Security](Security.html)
34 - [Static analysis](Static-analysis.html)
35 - [Theming](Theming.html)
36 - [Unit tests](Unit-tests.html)
37- About
38 - [FAQ](FAQ.html)
39 - [Community & Related software](Community-&-Related-software.html)
diff --git a/doc/md/Docker-101.md b/doc/md/docker/docker-101.md
index b02dd149..b02dd149 100644
--- a/doc/md/Docker-101.md
+++ b/doc/md/docker/docker-101.md
diff --git a/doc/md/Docker-resources.md b/doc/md/docker/resources.md
index 082d4a46..082d4a46 100644
--- a/doc/md/Docker-resources.md
+++ b/doc/md/docker/resources.md
diff --git a/doc/md/Reverse-proxy-configuration.md b/doc/md/docker/reverse-proxy-configuration.md
index 91ffecff..91ffecff 100644
--- a/doc/md/Reverse-proxy-configuration.md
+++ b/doc/md/docker/reverse-proxy-configuration.md
diff --git a/doc/md/Shaarli-images.md b/doc/md/docker/shaarli-images.md
index 25f6cfdd..6d108d21 100644
--- a/doc/md/Shaarli-images.md
+++ b/doc/md/docker/shaarli-images.md
@@ -7,7 +7,6 @@ repository.
7### Available image tags 7### Available image tags
8- `latest`: master branch (tarball release) 8- `latest`: master branch (tarball release)
9- `stable`: stable branch (tarball release) 9- `stable`: stable branch (tarball release)
10- `dev`: master branch (Git clone)
11 10
12All images rely on: 11All images rely on:
13- [Debian 8 Jessie](https://hub.docker.com/_/debian/) 12- [Debian 8 Jessie](https://hub.docker.com/_/debian/)
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-03 05:21:14 +0000