🔗 Pokole

Pokole is a simple and fast URL shortener that uses NodeJS and PostgreSQL.

🤔 Meaning

Pokole stands for 'short' in Hawaiian.

💻 Features

• Simplicity
• Ease of use
• In-depth statistics
• Written in TypeScript to ensure fast and bug-free code

🐳 Docker

Using Pokole in Docker is easier, faster and more convenient! Head over to Docker Hub for more information. Web UI built in!

📝 Requirements

• Node.js (12 or newer)
• node-gyp (required for building bcrypt)
• PostgreSQL (latest)

🔨 Usage

Here's an easy-to-follow tutorial:

• Install Node, node-gyp and PostgreSQL
• Create a new folder and install the package inside via npm (npm install pokole) or yarn (yarn add pokole)
• Create a JavaScript file inside the folder (e.g. server.js)
• Import the Pokole class from the package, create a new instance of the class, provide the required configuration and call the .start() function! You can find a sample script below:

// We import the Pokole class from the Pokole package
const { Pokole } = require("pokole");

// You need to provide an object containing crucial information for the package, so we define it here
const config = {
  // The database connection information
  db: {
    // The database user
    user: "alexthemaster",
    // The password used by the PostgreSQL user
    password: "eee23EfgZ",
    // The URL PostgreSQL can be accessed from
    host: "localhost",
    // The name of the database to use from PostgreSQL
    database: "pokole",
    // The port PostgreSQL uses (defaults to 5432)
    port: 5432,
  },
  // The URL the Pokole can be accessed from
  URL: "localhost",
  server: {
    //  The port Pokole should run on, (defaults to 80)
    port: 80,
  },
  // The JWT (JSON Web Token) secret you want to use - make sure to keep this private, as this is what's used to encrypt user tokens
  jwtSecret: "33HdAiM$4zGs",
  // Whether or not registration is enabled, defaults to true
  registration: true,
};

// We create a new Pokole instance, provide it with the required options and call the start function
new Pokole(config).start();

⚠ We recommend using a process manager such as PM2 to keep the script running!

📂 Hosting Static Files

If you want to host static files alongside Pokole, create a folder called static in the folder above and Pokole will serve the files inside this folder.

Pokole-Web is the default web dashboard included in the Docker build.

🕸 Routes / API

| Endpoint | Type | Headers | Body | Description | Returns (JSON) | Requires authentication | | ------------------- | ------ | --------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------- | | /api/register | GET | | | Check if registration is possible | enabled: boolean | No | | /api/register | POST | Content-Type: "application/json" | { email: string, username: string, password: string } | Register an account | success: string \| error: string | No | | /api/login | POST | Content-Type: "application/json" | { username: string, password: string } | Login to an existing account | { token: string, expiresIn: number } \| error: string | No | | /api/shorten | POST | Authorization: Bearer token, Content-Type: "application/json" | { url: string, custom?: string } | Shorten an URL | { success: string, URL: link } \| error: string | Yes | | /api/me/links | GET | Authorization: Bearer token | | Returns an array containing the list of your shortened URL's and and array of statistics for it | { longURL: link, shortURL: link, created_on: date, stats: [] } | Yes | | /api/me/links/:link | DELETE | Authorization: Bearer token, Content-Type: "application/json" | | Delete a shortlink | { success: string } \| { error: string } | Yes |

Legend: ? means the header is optional; | means OR; the string after : in the Returns column is the type of the returned object

Note: the token is only valid for an hour, so you will have to request a new one after that!