diff --git a/1.-Gist.md b/1.-Gist.md new file mode 100644 index 0000000..9e053ea --- /dev/null +++ b/1.-Gist.md @@ -0,0 +1,22 @@ +GIST is an open-source application to share code. +https://www.deblan.io/post/517/gist-est-dans-la-place + +### Editor + +![Gist](https://upload.deblan.org/u/2018-08/5b7ab7a6.png "Gist editor") + +### Result + +![Gist](https://upload.deblan.org/u/2018-08/5b7ab7d4.png "Gist result") + +### Account + +![Gist](https://upload.deblan.org/u/2018-08/5b7aba2d.png "Gist account") + +### Embeded Gist + +![Gist](https://upload.deblan.org/u/2018-08/5b7ab81c.png "Embeded Gist") + +--- + +[Next: 1.1 Requirements](https://gitnet.fr/deblan/gist/wiki/1.1+Requirements) \ No newline at end of file diff --git a/1.1-Requirements.md b/1.1-Requirements.md new file mode 100644 index 0000000..9c1eeb0 --- /dev/null +++ b/1.1-Requirements.md @@ -0,0 +1,18 @@ +* PHP >= 5.4 with PDO +* GIT +* MySQL or SQLite (PostgreSQL should work) +* Composer (php) +* NPM (nodejs) + +``` +$ sudo apt install npm php php-mysql mysql-server php-sqlite git +$ git config --global user.email "you@example.com" +$ git config --global user.name "Your Name" +$ curl -sS https://getcomposer.org/installer | php +$ chmod +x composer.phar +$ sudo mv composer.phar /usr/local/bin/composer +``` + +--- + +[Previous: 1. Gist](https://gitnet.fr/deblan/gist/wiki/1.+Gist) / [Next: 1.2 Installation](https://gitnet.fr/deblan/gist/wiki/1.2+Installation) \ No newline at end of file diff --git a/1.2-Installation.md b/1.2-Installation.md new file mode 100644 index 0000000..7c907c4 --- /dev/null +++ b/1.2-Installation.md @@ -0,0 +1,28 @@ + $ 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](https://gitnet.fr/deblan/gist/wiki/1.2.1+Configuration) for more information about configuration. + +--- + +[Previous: 1.1 Requirements](https://gitnet.fr/deblan/gist/wiki/1.1+Requirements) / [Next: 1.2.1 Configuration](https://gitnet.fr/deblan/gist/wiki/1.2.1+Configuration) \ No newline at end of file diff --git a/1.2.1-Configuration.md b/1.2.1-Configuration.md new file mode 100644 index 0000000..3db973b --- /dev/null +++ b/1.2.1-Configuration.md @@ -0,0 +1,41 @@ +### 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 + +**Versions >= 1.4.4 only**: `$ cp app/config/config.yml.dist app/config/config.yml` + +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`) + + +--- + +[Previous: 1.2 Installation](https://gitnet.fr/deblan/gist/wiki/1.2+Installation) / [Next: 1.2.2 Web server](https://gitnet.fr/deblan/gist/wiki/1.2.2+Web+server) \ No newline at end of file diff --git a/1.2.2-Web-server.md b/1.2.2-Web-server.md new file mode 100644 index 0000000..0baae70 --- /dev/null +++ b/1.2.2-Web-server.md @@ -0,0 +1,18 @@ +The web server must have permission to write into `data` and `cache`. + +``` +$ 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. + +--- + +[Previous: 1.2.1 Configuration](https://gitnet.fr/deblan/gist/wiki/1.2.1+Configuration) / [Next: 1.2.3 Cache](https://gitnet.fr/deblan/gist/wiki/1.2.3+Cache) \ No newline at end of file diff --git a/1.2.3-Cache.md b/1.2.3-Cache.md new file mode 100644 index 0000000..aa7e1c1 --- /dev/null +++ b/1.2.3-Cache.md @@ -0,0 +1,10 @@ +Gist generates two types of cache: + +* HTTP Cache using the header `Cache-Control` with `max-age` and `s-maxage` attributes (client and proxy TTLs) +* Files to preserve computing resources + +You can remove the directory `cache` anytime you want using `make clean-cache` or `rm -fr cache/*`. + +--- + +[Previous: 1.2.2 Web server](https://gitnet.fr/deblan/gist/wiki/1.2.2+Web+server) / [Next: 1.2.4 Makefile](https://gitnet.fr/deblan/gist/wiki/1.2.4+Makefile) \ No newline at end of file diff --git a/1.2.4-Makefile.md b/1.2.4-Makefile.md new file mode 100644 index 0000000..7a17e98 --- /dev/null +++ b/1.2.4-Makefile.md @@ -0,0 +1,26 @@ +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 clean-cache` will remove the content of the cache directory +* `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 + +--- + +[Previous: 1.2.3 Cache](https://gitnet.fr/deblan/gist/wiki/1.2.3+Cache) / [Next: 1.3 Upgrade](https://gitnet.fr/deblan/gist/wiki/1.3+Upgrade) \ No newline at end of file diff --git a/1.3-Upgrade.md b/1.3-Upgrade.md new file mode 100644 index 0000000..b76438f --- /dev/null +++ b/1.3-Upgrade.md @@ -0,0 +1,18 @@ +If your version is < v1.4.2, run: `test -d app && git add app && git commit -m "Configuration"`. + +### All versions + +``` +$ make update +$ make propel +``` + +If you upgrade from <= v1.4.0 to >= v1.4.1: run `php 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](https://gitnet.fr/deblan/gist/wiki/1.2.1+Configuration) for more information. + +If you upgrade to v1.7.0 or more, see the [configuration section](https://gitnet.fr/deblan/gist/wiki/1.2.1+Configuration) for more information about new options. + +--- + +[Previous: 1.2.4 Makefile](https://gitnet.fr/deblan/gist/wiki/1.2.4+Makefile) / [Next: 1.4 API](https://gitnet.fr/deblan/gist/wiki/1.4+API) \ No newline at end of file diff --git a/1.4-API.md b/1.4-API.md new file mode 100644 index 0000000..a8ebd7c --- /dev/null +++ b/1.4-API.md @@ -0,0 +1,174 @@ +### 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} +``` + +--- + +[Previous: 1.3 Upgrade](https://gitnet.fr/deblan/gist/wiki/1.3+Upgrade) / [Next: 1.5 Console](https://gitnet.fr/deblan/gist/wiki/1.5+Console) \ No newline at end of file diff --git a/1.5-Console.md b/1.5-Console.md new file mode 100644 index 0000000..31f118a --- /dev/null +++ b/1.5-Console.md @@ -0,0 +1,13 @@ +* **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` + +--- + +[Previous: 1.4 API](https://gitnet.fr/deblan/gist/wiki/1.4+API) / [Next: 1.6 Contributors](https://gitnet.fr/deblan/gist/wiki/1.6+Contributors) \ No newline at end of file diff --git a/1.6-Contributors.md b/1.6-Contributors.md new file mode 100644 index 0000000..760a103 --- /dev/null +++ b/1.6-Contributors.md @@ -0,0 +1,16 @@ +**Developers** + +* Simon Vieille + +**Translators** + +* Simon Vieille +* Marion Sanchez +* Marjorie Da Silva +* Mélanie Chanat +* Showfom +* Tavin + +--- + +[Previous: 1.6 Contributors](https://gitnet.fr/deblan/gist/wiki/1.6+Contributors) \ No newline at end of file