Explorer

Explore and share. Highly-configurable directory listing made with nodejs.

Requirements

• nodejs (> 0.11 with harmony support)

Installing nodejs with nvm

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.25.4/install.sh | bash
nvm install 0.12 #nvm ls-remote to see available versions
nvm alias default 0.12

Install

As a pm2 module

npm i pm2 -g
pm2 install xplorer

Go to IP:4859, login with admin:admin Don't forget to change the password.

With pm2 configuration file is located in ~/.config/explorer

You may want to create your own HTTPS certs or disable it (see below).

Manual

Download, unpack, configure, launch :

curl -L https://github.com/soyuka/explorer/archive/v2.0.12.tar.gz | tar xz
cd explorer-2.0.12
cp config.example.yml config.yml #copy default configuration
cp users.default data/users #copy default database
npm rebuild
node --harmony index.js #see below to run as a daemon

Mirror

curl -L http://lab.wareziens.net/soyuka/explorer/repository/archive.tar.gz?ref=v2.0.12 | tar xz

Check IP:4859, login with admin:admin. Don't forget to change the password!

Run

Installed as a pm2 module explorer will already be daemonized.

Daemonize with pm2

npm i pm2 -g
pm2 start --node-args="--harmony" --name explorer index.js

With iojs you can run:

pm2 --next-gen-js --name explorer start index.js

Or with babel-node:

npm i pm2 babel-node -g
pm2 --interpreter babel-node --name explorer start index.js

Configuration

---
search: 
  # Available: pt, ack, find, mdfind, custom, native
  method: 'native' 
  # Custom search command (${search} will be replaced by the string) 
  command: "pt --nocolor --nogroup -l -i '${search}' ." # not used by native
  max_depth: 10 # Default 10
  concurrency: 100 # Default 100 (only used with native search)
  # String match score (only used with native search)
  maxScore: 0.5
pagination:
  # Maximum number of items per page
  limit: 10 # Default 100
# Be carefull with this next section as it will have an impact on performances
tree:
  # When calculating directory size we stop at the max_depth
  max_depth: 10 #Default 10
  concurrency: 100 #Default 100
remove: 
  # 'mv' will move files to a trash directory
  # 'rm' will delete files
  # empty to disable deletion
  method: 'mv' #default is to move
  path: './trash'
archive:
  keep: false # set to true to keep archives
  path: './tmp'
upload:
  path: './upload'
  concurrency: 10
  maxSize: '50mb' # default to 50mb see https://github.com/expressjs/body-parser#limit
  maxCount: 10 # max number of files 
# note that path values will be overridden by the user path if set
# path will be created if non-existant
database: './data/users' # don't touch if you don't know what you're doing
app_root: '/' # app root for client ressources
session_secret: 'Some string here' #Change this
port: 4859
https:
  port: 6859
  enabled: true #default option!
  key: './certs/key.pem' #change those are dummies
  cert: './certs/cert.pem'
dev: false # more verbose error (stack)

The config.yml will be searched in:

• ~/.config/explorer/config.yml
• ./config/explorer/config.yml (relative to the script directory!)

To reload the configuration you'll need to restart the script pm2 restart xplorer!

HTTP(S)

Nginx

upstream explorer {
  server localhost:4859 #port can be changed in the config.yml
}

server {
  listen 80;

  location / { #if you want to change this, change `app_root` in the config.yml
    proxy_pass http://explorer/ 
  }
}

Certs

You can either change the paths in the config.yml, or replace those located in your configuration path (see Configuration).

Rss

By calling your tree url or a search path (localhost:4859/search?search=*.mkv&key=my-key), set the Accept header to application/rss+xml:

http GET localhost:4859/?key=get-your-key-from-settings Accept:application/rss+xml

Update

From 1.x to 2.x see configuration migration.

As a pm2 module

pm2 install xplorer

From tarball

cd /path/to/your/explorer
curl -L https://github.com/soyuka/explorer/archive/v1.0.6.tar.gz | tar xz --strip-components 1
npm rebuild

Development

1. Clone
2. Follow the manual installation to copy default files
3. Launch

The easiest is to compile with babel for ES6 compatibility, for example:

DEBUG="explorer:*, explorer:routes:*" babel-node index.js

Sass is compiled with gulp, for example:

gulp watch

To get stack traces from errors use dev: true in your configuration file.

Tests

Tests are using their own configuration file test/fixtures/config.yml:

mocha --compilers js:babel/register

Api docs

Generated with apidocjs (available here):

apidoc -i routes -o doc/api

Performances

We use Bluebird with concurrency, for your information you may speed things up:

$ sync && echo 3 > /proc/sys/vm/drop_caches
$ node test.js 1
reading files 35ms
$ sync && echo 3 > /proc/sys/vm/drop_caches
$ node test.js Infinity
reading files: 9ms

See bluebird docs

Why?

I did this because I could not find a light file explorer. It had to be simple, easy to install and fast. I tried pydio but it's heavy and long to install. I also tried h5ai but it does not have user support and has a lot of client-side javascript. I also have the feeling that it's slow. Explorer was built with only 2 client javascript lines. It's fun to see how hard it seems, nowadays, to avoid using javascript for apps that don't require it.

KISS.