Table of Contents

• GIST
  • Requirements
    • Git
    • Composer
    • NPM
  • Installation
  • Upgrade
  • Configuration
  • Makefile
  • API
  • Console
  • Deployment
  • Contributors

GIST

GIST is an open-source application to share code. https://www.deblan.io/post/517/gist-est-dans-la-place

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 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). 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 for more information.

If you upgrade to v1.7.0 or more, see the configuration section 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:

{
    "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:

{
    "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:

[
    {
        "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:

{
    "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:

{
    "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:

{"error":false}

Response code 400:

{"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