mirror of
https://gitnet.fr/deblan/gist.git
synced 2021-08-14 08:30:49 +02:00
Documentation moved to the WIKI
This commit is contained in:
parent
999b4a25a7
commit
af30221295
381
README.md
381
README.md
@ -1,388 +1,11 @@
|
|||||||
Table of Contents
|
|
||||||
=================
|
|
||||||
|
|
||||||
* [GIST](#gist)
|
|
||||||
* [Requirements](#requirements)
|
|
||||||
* [Git](#git)
|
|
||||||
* [Composer](#composer)
|
|
||||||
* [NPM](#npm)
|
|
||||||
* [Installation](#installation)
|
|
||||||
* [Upgrade](#upgrade)
|
|
||||||
* [Configuration](#configuration)
|
|
||||||
* [Makefile](#makefile)
|
|
||||||
* [API](#api)
|
|
||||||
* [Console](#console)
|
|
||||||
* [Deployment](#deployment)
|
|
||||||
* [Contributors](#contributors)
|
|
||||||
|
|
||||||
|
|
||||||
GIST
|
GIST
|
||||||
====
|
====
|
||||||
|
|
||||||
GIST is an open-source application to share code.
|
GIST is an open-source application to share code.
|
||||||
https://www.deblan.io/post/517/gist-est-dans-la-place
|
https://www.deblan.io/post/517/gist-est-dans-la-place
|
||||||
|
|
||||||
|
[Read the wiki for more information](https://gitnet.fr/deblan/gist/wiki/_pages).
|
||||||
|
|
||||||
![Gist](https://upload.deblan.org/u/2015-11/565b93a5.png "Gist")
|
![Gist](https://upload.deblan.org/u/2015-11/565b93a5.png "Gist")
|
||||||
|
|
||||||
![Gist](https://upload.deblan.org/u/2016-06/57655dec.png "Gist")
|
![Gist](https://upload.deblan.org/u/2016-06/57655dec.png "Gist")
|
||||||
|
|
||||||
|
|
||||||
Requirements
|
|
||||||
------------
|
|
||||||
|
|
||||||
* PHP >= 5.4 with PDO
|
|
||||||
* GIT
|
|
||||||
* MySQL or SQLite (PostgreSQL should work)
|
|
||||||
* Composer (php)
|
|
||||||
* NPM (nodejs)
|
|
||||||
|
|
||||||
### Git
|
|
||||||
|
|
||||||
Git can maybe be downloaded from your system's repositories.
|
|
||||||
|
|
||||||
$ git config --global user.email "you@example.com"
|
|
||||||
$ git config --global user.name "Your Name"
|
|
||||||
|
|
||||||
### Composer
|
|
||||||
|
|
||||||
Composer can maybe be downloaded from your system's repositories.
|
|
||||||
Else, follow the next instructions:
|
|
||||||
|
|
||||||
# With cURL
|
|
||||||
$ curl -sS https://getcomposer.org/installer | php
|
|
||||||
|
|
||||||
# With Wget
|
|
||||||
$ wget -O - -q https://getcomposer.org/installer | php
|
|
||||||
|
|
||||||
$ chmod +x composer.phar
|
|
||||||
|
|
||||||
# For a local installation and if the envvar PATH contains "$HOME/bin/"
|
|
||||||
$ mv composer.phar ~/bin/composer
|
|
||||||
|
|
||||||
# For a global installation
|
|
||||||
$ sudo mv composer.phar /usr/local/bin/composer
|
|
||||||
|
|
||||||
### NPM
|
|
||||||
|
|
||||||
$ sudo apt install npm
|
|
||||||
|
|
||||||
Installation
|
|
||||||
------------
|
|
||||||
|
|
||||||
$ cd /path/to/www/
|
|
||||||
$ git clone https://gitnet.fr/deblan/gist
|
|
||||||
$ cd gist
|
|
||||||
$ make
|
|
||||||
|
|
||||||
An interactive shell will start. If you want to run the interactive shell manually, run:
|
|
||||||
|
|
||||||
$ composer gist-scripts
|
|
||||||
|
|
||||||
To perform a manual configuration, follow these instructions.
|
|
||||||
|
|
||||||
With `MySQL`:
|
|
||||||
|
|
||||||
$ cp app/config/propel.yaml.dist-mysql propel.yaml
|
|
||||||
|
|
||||||
With `SQLite`:
|
|
||||||
|
|
||||||
$ cp app/config/propel.yaml.dist-sqlite propel.yaml
|
|
||||||
|
|
||||||
Then edit `propel.yaml` and replace the values of `dsn`, `user`, `password` by considering your environment and run `$ make propel`.
|
|
||||||
|
|
||||||
**Versions >= 1.4.4 only**: `$ cp app/config/config.yml.dist app/config/config.yml`
|
|
||||||
|
|
||||||
See the [configuration section](#configuration) for more information about configuration.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
The web server must have permission to write into `data`.
|
|
||||||
|
|
||||||
$ sudo chown -R www-data:www-data data
|
|
||||||
|
|
||||||
Your webserver must be configured to serve `web/` as document root. If you use nginx, all virtual paths must be rooted with `web/index.php` or `web/app_dev.php` ([documentation](https://www.nginx.com/resources/wiki/start/topics/recipes/symfony/)). If you use apache, you must enable the `rewrite` module and restart:
|
|
||||||
|
|
||||||
$ sudo a2enmod rewrite
|
|
||||||
$ sudo service apache2 restart
|
|
||||||
|
|
||||||
`app_dev.php` is the development router. Access is granted for an IP range defined in the same file.
|
|
||||||
|
|
||||||
Upgrade
|
|
||||||
-------
|
|
||||||
|
|
||||||
If your version is less than v1.4.2, run: `test -d app && git add app && git commit -m "Configuration"`.
|
|
||||||
|
|
||||||
$ make update
|
|
||||||
$ make propel
|
|
||||||
|
|
||||||
If you upgrade from <= v1.4.0 to >= v1.4.1: `app/console migrate:to:v1.4.1`.
|
|
||||||
|
|
||||||
If you upgrade from <= v1.4.3 to >= v1.4.4, the configuration is moved to `app/config/config.yml`: `$ cp app/config/config.yml.dist app/config/config.yml` and see the [configuration section](#configuration) for more information.
|
|
||||||
|
|
||||||
If you upgrade to v1.7.0 or more, see the [configuration section](#configurationh) for more information about new options.
|
|
||||||
|
|
||||||
Configuration
|
|
||||||
-------------
|
|
||||||
|
|
||||||
### Version < 1.4.4
|
|
||||||
|
|
||||||
Edit `app/bootstrap.php.d/70-security.php`.
|
|
||||||
|
|
||||||
* `$app['token']`: the securty token (a strong passphrase).
|
|
||||||
* `$app['enable_registration']`: defines if the registration is allowed (`true` or `false`)
|
|
||||||
* `$app['enable_login']`: defines if the login is allowed (`true` or `false`)
|
|
||||||
* `$app['login_required_to_edit_gist']`: defines if the user must be logged to create or clone a Gist (`true` or `false`)
|
|
||||||
* `$app['login_required_to_view_gist']`: defines if the user must be logged to view a Gist (`true` or `false`)
|
|
||||||
* `$app['login_required_to_view_gist']`: defines if the user must be logged to view an embeded Gist (`true` or `false`)
|
|
||||||
|
|
||||||
If you install Gist on your server, you have to modify the `base_uri` of the API.
|
|
||||||
Edit `app/bootstrap.php.d/60-api.php` and replace `https://gist.deblan.org/`.
|
|
||||||
|
|
||||||
### Version >= 1.4.4
|
|
||||||
|
|
||||||
Edit `app/config/config.yml`.
|
|
||||||
|
|
||||||
* `security.token`: the securty token (a strong passphrase)
|
|
||||||
* `security.enable_registration`: defines if the registration is allowed (`true` or `false`)
|
|
||||||
* `security.enable_login`: defines if the login is allowed (`true` or `false`)
|
|
||||||
* `security.login_required_to_edit_gist`: defines if the user must be logged to create or clone a Gist (`true` or `false`)
|
|
||||||
* `security.login_required_to_view_gist`: defines if the user must be logged to view a Gist (`true` or `false`)
|
|
||||||
* `security.login_required_to_view_gist`: defines if the user must be logged to view an embeded Gist (`true` or `false`)
|
|
||||||
* `api.base_uri`: The url of your instance.
|
|
||||||
* `data.path`: the path where the files are saved.
|
|
||||||
* `git.path`: The path of `git`.
|
|
||||||
* `theme.name`: the name of the theme (`dark` or `light`)
|
|
||||||
|
|
||||||
### Version >= v1.7.0
|
|
||||||
|
|
||||||
* `api.enabled`: defines if the API is enabled (`true` or `false`)
|
|
||||||
* `api.api_key_required`: defines if the API key is required to access the API (`true` or `false`)
|
|
||||||
* `api.client.api_key`: defines the client API key (`string`)
|
|
||||||
|
|
||||||
Makefile
|
|
||||||
--------
|
|
||||||
|
|
||||||
A Makefile is provided to automate some tasks.
|
|
||||||
|
|
||||||
* `make` will install dependencies via composer and NPM
|
|
||||||
* `make composer` will install PHP dependencies via composer
|
|
||||||
* `make npm` will install CSS/JS dependencies via NPM
|
|
||||||
* `make update` will update the application
|
|
||||||
* `make propel` will generate propel migrations (database and files)
|
|
||||||
* `make run` will run development server on http://127.0.0.1:8080/
|
|
||||||
|
|
||||||
By default, `composer`, `npm`, `git`, `mkdir` and `php` binaries must be in your `$PATH`. You can override it by using these envars:
|
|
||||||
|
|
||||||
* `COMPOSER`
|
|
||||||
* `NPM`
|
|
||||||
* `GIT`
|
|
||||||
* `MKDIR`
|
|
||||||
* `PHP`
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
$ export COMPOSER=/path/to/composer
|
|
||||||
$ make composer
|
|
||||||
|
|
||||||
API
|
|
||||||
---
|
|
||||||
|
|
||||||
### Version < v1.7.0
|
|
||||||
|
|
||||||
#### Create a new gist
|
|
||||||
|
|
||||||
**POST** /{locale}/api/create
|
|
||||||
Params:
|
|
||||||
|
|
||||||
* `form[title]`: String (required, can be empty)
|
|
||||||
* `form[type]`: String (required)
|
|
||||||
Values: html, css, javascript, php, sql, xml, yaml, perl, c, asp, python, bash, actionscript3, text
|
|
||||||
* `form[content]`: String (required)
|
|
||||||
|
|
||||||
**Responses:**
|
|
||||||
|
|
||||||
* Code `405`: Method Not Allowed
|
|
||||||
* Code `400`: Bad Request
|
|
||||||
* Code `200`: A json which contains gist's information. Example:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
{
|
|
||||||
"url": "https:\/\/gist.deblan.org\/en\/view\/55abcfa7771e0\/f4afbf72967dd95e3461490dcaa310d728d6a97d",
|
|
||||||
"gist": {
|
|
||||||
"Id": 66,
|
|
||||||
"Title": "test prod",
|
|
||||||
"Cipher": false,
|
|
||||||
"Type": "javascript",
|
|
||||||
"File": "55abcfa7771e0",
|
|
||||||
"CreatedAt": "2015-07-19T16:26:15Z",
|
|
||||||
"UpdatedAt": "2015-07-19T16:26:15Z"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Update an existing gist
|
|
||||||
|
|
||||||
**POST** /{locale}/api/update/{id}
|
|
||||||
Params:
|
|
||||||
|
|
||||||
* `{id}`: Gist Id (required)
|
|
||||||
* `form[content]`: String (required)
|
|
||||||
|
|
||||||
**Responses:**
|
|
||||||
|
|
||||||
* Code `405`: Method Not Allowed
|
|
||||||
* Code `400`: Bad Request
|
|
||||||
* Code `200`: A json which contains gist's information. Example:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
{
|
|
||||||
"url": "https:\/\/gist.deblan.org\/en\/view\/55abcfa7771e0\/abcgi72967dd95e3461490dcaa310d728d6adef",
|
|
||||||
"gist": {
|
|
||||||
"Id": 66,
|
|
||||||
"Title": "test prod",
|
|
||||||
"Cipher": false,
|
|
||||||
"Type": "javascript",
|
|
||||||
"File": "55abcfa7771e0",
|
|
||||||
"CreatedAt": "2015-07-19T16:26:15Z",
|
|
||||||
"UpdatedAt": "2015-07-19T16:30:15Z"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Version >= v1.7.0
|
|
||||||
|
|
||||||
Invalid response codes:
|
|
||||||
|
|
||||||
* Code `401`: Unauthorized
|
|
||||||
* Code `403`: API not enabled
|
|
||||||
* Code `405`: Method Not Allowed
|
|
||||||
* Code `400`: Bad Request
|
|
||||||
|
|
||||||
#### List gists
|
|
||||||
|
|
||||||
**GET** /{locale}/api/list/{apiToken}
|
|
||||||
|
|
||||||
Response example:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
[
|
|
||||||
{
|
|
||||||
"id": 66,
|
|
||||||
"title": "test prod",
|
|
||||||
"cipher": false,
|
|
||||||
"type": "javascript",
|
|
||||||
"file": "55abcfa7771e0",
|
|
||||||
"createdAt": "2015-07-19T16:26:15Z",
|
|
||||||
"updatedAt": "2015-07-19T16:30:15Z"
|
|
||||||
"url": "https:\/\/gist.deblan.org\/en\/view\/55abcfa7771e0\/abcgi72967dd95e3461490dcaa310d728d6adef",
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 67,
|
|
||||||
"title": "test prod 2",
|
|
||||||
"cipher": false,
|
|
||||||
"type": "javascript",
|
|
||||||
"file": "xyzbcfa7771e0",
|
|
||||||
"createdAt": "2015-08-19T16:26:15Z",
|
|
||||||
"updatedAt": "2015-08-19T16:30:15Z"
|
|
||||||
"url": "https:\/\/gist.deblan.org\/en\/view\/5byzbcfa7771e0\/def72967dd95e346koq0dcaa310d728d6artu",
|
|
||||||
},
|
|
||||||
...
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Create a new gist
|
|
||||||
|
|
||||||
**POST** /{locale}/api/create/{apiToken}
|
|
||||||
Params:
|
|
||||||
|
|
||||||
* `form[title]`: String (required, can be empty)
|
|
||||||
* `form[type]`: String (required)
|
|
||||||
Values: html, css, javascript, php, sql, xml, yaml, perl, c, asp, python, bash, actionscript3, text
|
|
||||||
* `form[content]`: String (required)
|
|
||||||
|
|
||||||
Response example:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
{
|
|
||||||
"url": "https:\/\/gist.deblan.org\/en\/view\/55abcfa7771e0\/f4afbf72967dd95e3461490dcaa310d728d6a97d",
|
|
||||||
"gist": {
|
|
||||||
"id": 66,
|
|
||||||
"title": "test prod",
|
|
||||||
"cipher": false,
|
|
||||||
"type": "javascript",
|
|
||||||
"file": "55abcfa7771e0",
|
|
||||||
"createdAt": "2015-07-19T16:26:15Z",
|
|
||||||
"updatedAt": "2015-07-19T16:26:15Z"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Update an existing gist
|
|
||||||
|
|
||||||
**POST** /{locale}/api/update/{id}/{apiToken}
|
|
||||||
Params:
|
|
||||||
|
|
||||||
* `{id}`: Gist Id (required)
|
|
||||||
* `form[content]`: String (required)
|
|
||||||
|
|
||||||
Response example:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
{
|
|
||||||
"url": "https:\/\/gist.deblan.org\/en\/view\/55abcfa7771e0\/abcgi72967dd95e3461490dcaa310d728d6adef",
|
|
||||||
"gist": {
|
|
||||||
"id": 66,
|
|
||||||
"title": "test prod",
|
|
||||||
"cipher": false,
|
|
||||||
"type": "javascript",
|
|
||||||
"file": "55abcfa7771e0",
|
|
||||||
"createdAt": "2015-07-19T16:26:15Z",
|
|
||||||
"updatedAt": "2015-07-19T16:30:15Z"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Delete an existing gist
|
|
||||||
|
|
||||||
**POST** /{locale}/api/delete/{id}/{apiToken}
|
|
||||||
|
|
||||||
Response code `200`:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
{"error":false}
|
|
||||||
```
|
|
||||||
|
|
||||||
Response code `400`:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
{"message":"Invalid Gist", "error":true}
|
|
||||||
```
|
|
||||||
|
|
||||||
Console
|
|
||||||
-------
|
|
||||||
|
|
||||||
* **Create a gist**: `$ app/console --help create`
|
|
||||||
* **Update a gist**: `$ app/console --help update`
|
|
||||||
* **Create user**: `$ app/console --help user:create`
|
|
||||||
* **Show stats**: `$ app/console --help stats`
|
|
||||||
|
|
||||||
### Version >= v1.7.0
|
|
||||||
|
|
||||||
* **List your gists**: `$ app/console --help gists`
|
|
||||||
* **Delete a gist**: `$ app/console --help delete`
|
|
||||||
|
|
||||||
Contributors
|
|
||||||
------------
|
|
||||||
|
|
||||||
**Developers**
|
|
||||||
|
|
||||||
* Simon Vieille <contact@deblan.fr>
|
|
||||||
|
|
||||||
**Translators**
|
|
||||||
|
|
||||||
* Simon Vieille <contact@deblan.fr>
|
|
||||||
* Marion Sanchez
|
|
||||||
* Marjorie Da Silva
|
|
||||||
* Mélanie Chanat
|
|
||||||
* Showfom
|
|
||||||
* Tavin
|
|
||||||
|
Loading…
Reference in New Issue
Block a user