Quick Start

Last updated: April 18th, 2019

Requirements

  • A web server with PHP support, for example:
  • PHP 5.6.x or greater
  • PHP extensions are required:
    • php-mbstring

Installation

We will give an example of installation on Apache server on Ubuntu operating system. The default document root for Apache is `/var/www/html` (Ubun14.04 or later).

Unpack the uploaded archive to any folder on your server with the next command:

unzip nrg-uploader.zip

After last command you will get two folders:

/dev
/release

Copy the content of `./release` folder to any folder within web root of the server with the next command:

cp -a ./release/ /var/www/html/uploader/

Note: use `sudo` to execute the command above if you face a permissions issue

Ultimately you will get the next structure of folders:

var/www/html
       /uploader
               /docs
               /server
               /static
               /uploads
               /favicon.ico
               /index.php

Now just open an url that's related to the application folder:

http://my-site.com/uploader/

If necessary, set uploads folder permissions to `755` it's equal to `rwxr-xr-x` (see `uploadsFolder` parameter in configuration section)

If you are using nginx server then add following code to server config:
`location %application-folder%/server { deny all; return 403; }`
It's necessary for server side protection

Configuration

The main configuration file location is `%application-folder%/server/config.json`

Name Default Description
mode production The mode in which the application is running. May have two values `production` and `development`. In the development mode the application will return more details about errors
uploadsFolder ../uploads File upload folder
maxSize 1 GB Maximum allowed uploaded file size. Note that php.ini setting has precedence over this setting.
allowExtensions null Array of allowed file extensions. If missing or equals to null then all file types are allowed. Note that denyExtensions option has precedence over this setting.
denyExtensions null Array of denied file extensions. If missing or equals to null then all file types are allowed. Note this option has precedence over allowExtensions option.
authorization false If the value is true, then the application will work only with authorized users. The list of users those have access is in `%application-folder%/server/resources/users.json`. Please change an email and password for your own users before use the application in production. If you want to use your own authorization, then set the value of this parameter to false. (see Using with custom login section)
signature ********* This value is used to encrypt access tokens if the parameter `authorization` is true. Please generate your own value for it before use the application in production.
directFileAccess false If the value is true, then the application will use a direct URL to open files (see File access section)
directFileUrl /uploads The Url relative to the root of the application corresponding to the folder with the uploaded files on the server. That folder is specified in parameter `uploadsFolder`

Parameters

Parameters is a simple object that you pass to the constructor of the application class when you create an application instance (see usage section)

Name Default Description
apiUrl . URL for the server side of the application
wrapper document.body Container to render the application is native DOM Element instance. You can get it just by the following code:
document.getElementById('app')

Usage

Example: how to embed in HTML page
// path: %application-folder%/index.php

<?php
if (!empty($_GET['r'])) {
    require __DIR__.'/server/run.php';
    exit(0);
}
?><!doctype html>
<html lang="en">
<head>
	<title>File Uploader</title>
	<meta charset="utf-8"/>
	<link href="./static/css/nrg-uploader.min.css" rel="stylesheet">
</head>
<body>

<div id="uploader"></div>

<script src="./static/js/nrg-uploader.min.js"></script>
<script language="JavaScript">
  var uploader = new $nrg.Uploader({
    apiUrl: '.',
    wrapper: document.getElementById('uploader')
  })

  uploader.run()
</script>
</body>
</html>
Example: how to use with custom login
// path: %application-folder%/index.php

<?php
/**
    Here we check if the user is logged in
    if necessary we send the user to the login page
*/
if (!isset($_SESSION['user'])) {
    header('Location: /login', true, 302);
    exit();
}

if (!empty($_GET['r'])) {
    require __DIR__.'/server/run.php';
    exit(0);
}
?><!doctype html>
<html lang="en">
<head>
	<title>File Uploader</title>
	<meta charset="utf-8"/>
	<link href="./static/css/nrg-uploader.min.css" rel="stylesheet">
</head>
<body>

<div id="uploader"></div>

<script src="./static/js/nrg-uploader.min.js"></script>
<script language="JavaScript">
  var uploader = new $nrg.Uploader({
    apiUrl: '.',
    wrapper: document.getElementById('uploader')
  })

  uploader.run()
</script>
</body>
</html>

File access

By default, after installation, you will have access to uploaded files by following url (Replace `{file.png}` to real file name):

http://my-site.com/uploader/?r=/open&fileName={file.png}

If you are using custom login then only logged in users can open uploaded files. Otherwise any visitor cans open file by url specified above

If you want to have direct file access that you can just to delete file `%application-folder%/uploads/.htaccess` and set `directFileAccess` param to true (see Configuration section). Then open file by following url (Replace `{file.png}` to real file name):

http://my-site.com/uploader/uploads/{file.png}

If you are going to change the uploads folder location then modify `uploadsFolder` and `directFileUrl` parameters from `%application-folder%/server/config.json` file (see an example below).

// path: %application-folder%/server/config.json
{
  ...
  "directFileUrl": "/uploads",
  "uploadsFolder": "../uploads",
  ...
}

Theming

There are theme files in the next folder:

%application-folder%/static/css/nrg-uploader.min.css
%application-folder%/static/css/nrg-uploader-dark.min.css

You can use one of them when choosing the theme of the application. Just add `link` tag in the header section:

// // path: %application-folder%/index.php
<link href="./static/css/nrg-uploader-dark.min.css" rel="stylesheet">

Also you can develop your own theme by change `css` files. Or as more advanced way you can change `scss` files and then rebuild the application (see development section).

Development

The client part of the application was created with Create React App. The server part of the application was created with PHP. So a development new features or modifications requires the next tools to be installed:

  • Node 8.10.0 or greater
  • Yarn 1.10.0 or greater
  • PHP 5.6.x or greater
  • Apache 2.0 or greater or Nginx 1.1 or greater

The application source code is in the folder `dev` of the downloaded archive:

The application has the next structure:

/public
/scripts
/src
/www
/config-overrides.js
/package.json

The server part of the application is in `www/server` and the client part of the application is in 'src'

To local deploy the application you can use the next command:

yarn

To build the application after making code changes you can use the next command:

yarn release

After that command is finished all you need to deploy new version of the application will be in `www` folder of the project structure

Just put content of `www` folder to the folder where you has earlier installed the application on your production web server (see installation section)