fileshack

drop your items

fileshack allows you to create your own simple, hosted web file storage

Getting Started

Installation

Fileshack can be hosted on your own server or on Google AppEngine. While the latter is better if you prefer hosting for free (up to a certain amount of traffic), the former means you do not have to disclose your files to a third party.

Fileshack is available for any purpose, but please don't use it for sharing copyrighted or other such content.

Native Installation

Fileshack is based on the web development framework Django. In order to deploy fileshack on your server, you first need to have a working web server such as Apache or nginx. There are countless ways of deploying Django. One of the most popular and simple combinations is Apache and mod_wsgi, which will be covered here. Other convenient combinations are Apache or nginx with FastCGI or gunicorn, possibly with Django run on startup by supervisord. It should also be possible to run fileshack on Windows with IIS. You will sure be able to find instructions for installing Django projects in these other combinations on the web.

Apache and mod_wsgi

If you run a Linux or a BSD distribution, both Apache and mod_wsgi are likely available via the distribution's packaging system. We will put Django and fileshack inside a virtualenv. Assuming Apache, mod_wsgi and virtualenv are installed, follow these steps:

Substitute your preferred installation directory for /home/user/www/fs/ and your domain for fileshack.example.org.
  1. Create a new virtualenv:
    mkdir -p /home/user/www
    cd /home/user/www
    virtualenv --no-site-packages fs
    cd fs
    . bin/activate
  2. Install django inside the virtual environment:
    pip install django
  3. Clone the fileshackproject repository:
    git clone git://github.com/peterkuma/fileshackproject.git
    cd fileshackproject
  4. Copy and customize the local settings example file:
    cp fileshackproject/settings_local-example.py fileshackproject/settings_local.py
    vi fileshackproject/settings_local.py
    Normally, you do not need to modify anything except for ADMINS, SECRET_KEY, and uncommenting DEBUG = False once your installation works properly.
  5. Initialize database:
    ./manage.py syncdb
    You will be asked to create a superuser account, by which you can later log in to the administration interface at http://fileshack.example.org/admin/. This command also creates a default store.
  6. Collect static files into the static directory:
    ./manage.py collectstatic --noinput
  7. At this point you can try to run fileshack with the integrated development server:
    ./manage.py runserver
    The default store should be accessible at http://localhost:8000. If everything works fine, continue with setting up Apache.
  8. Make sure Apache has a permission to write to db, the database file db/fileshack.sqlite and media.
    sudo chown www-data db db/fileshack.sqlite media

    media is the directory where fileshack stores the uploaded files. If you like, you can make it a symlink to a different directory on the file system.

  9. Create a new virtual host in the Apache configuration:
    <VirtualHost *:80>
       ServerName fileshack.example.org
       DocumentRoot /home/user/www/fs/
       ErrorLog /var/log/apache2/fileshack_error.log
       CustomLog /var/log/apache2/fileshack_access.log common

       <Location />
           Options -Indexes
       </Location>

       Alias /static/ /home/user/www/fs/fileshackproject/static/
       Alias /media/ /home/user/www/fs/fileshackproject/media/
       WSGIScriptAlias / /home/user/www/fs/fileshackproject/fileshackproject/wsgi_virtualenv.py
    </VirtualHost>
    wsgi_virtualenv.py is the WSGI application for use with virtualenv. Use wsgi.py instead if you decide not to use virtualenv.
  10. Test the configuration and restart apache:
    apache2ctl configtest
    apache2ctl restart
  11. Fileshack should now be accessible at http://fileshack.example.org. You can manage stores in the administration interface at http://fileshack.example.org/admin/. You are advised to protect the default store by an access code. If you encounter any problems, drop an e-mail to the mailing list at fileshack-general@lists.sourceforge.net.
    Do not forget to set DEBUG = False in settings_local.py before going public. Otherwise, users are presented with ugly HTTP 404 and HTTP 500 pages, potentially revealing sensitive information. Moreover, the django project is configured to serve static files, which is strongly discouraged in production environments (this should be the task of the web server).

Store Watching (optional)

Fileshack allows users to opt in to receive e-mail notifications when new files are uploaded. When enabled, a Watch button is displayed next to the Logout button, allowing users to enter an e-mail address to which to send notifications. However, several more steps need to be taken in order to support this feature.

Cron

If you want your fileshack installation to support store watching, you have to set up periodic requests to the service which sends the notifications:

http://fileshack.example.org/cron/

For security reasons, access to this URL is allowed only from hosts specified in the configuration variable FILESHACK_CRON_HOSTS, or to those who present with the shared secret FILESHACK_CRON_SECRET.

On Linux and other unix-like systems, periodic requests to a URL can be accomplished by a scheduled command in the system daemon cron. In order to schedule such a request every 10 minutes, create a file /etc/cron.d/fileshack:

# Run scheduled tasks of the web application fileshack.
#
*/10 * * * * user python -c 'import sys, httplib; c=httplib.HTTPConnection("fileshack.example.org"); c.request("POST","/cron/","secret=yoursecret"); r=c.getresponse(); r.status==200 or sys.stdout.write(r.read())'

Replace user with your username, and fileshack.example.org with the correct hostname of your fileshack installation.

If the hostname is not localhost, you will have to set up a shared secret. Replace yoursecret in the command above with your chosen secret, and set FILESHACK_CRON_SECRET in fileshackproject/settings_local.py to the same value.

Alternatively, you can add the IP address of the cron machine to FILESHACK_CRON_HOSTS. In this case, you do not have to supply the shared secret. By default, FILESHACK_CRON_HOSTS contains only localhost.

If anything goes wrong with the cron command, you should receive an e-mail with the command output on your user account from cron. In any case, you can test by executing the python command above in the console. Alternatively, the same can be accomplised more simply with:
curl -d secret=yoursecret http://fileshack.example.org/cron/
Settings

Store watching requires several configuration variables to be set up properly — mail server settings EMAIL_*, FILESHACK_EMAIL_FROM and SECRET_KEY in fileshackproject/settings_local.py. Mail server settings are described in detail in the django documentation.

You have reload Apache in order for the new settings to be applied.
If you do not set SECRET_KEY, users will not be able to unsubscribe via a link in notification messages. These links are protected by HMAC, which requires a private secret.
Admin

In Sites, modify the example.org domain to reflect your domain setting.

Finally, you can enable Allow watch in your chosen stores. To prevent bothering users with copious amounts of messages, at most one notification is sent per 6-hour period to a particular e-mail address. This can be tuned by the Watch delay option.

Google AppEngine

Google AppEngine is an application hosting service provided by Google. The good thing about AppEngine is that your application is hosted for free as long as you stay below rather high limits of bandwidth and storage capacity. The bad thing is that it requires a special API to be used for managing files, which prevents fileshack from running as efficiently as a native installation, and some features such as downloading of unfinished files are not supported. The demo on this site is hosted on Google AppEngine.

If you decided to deploy fileshack on Google AppEngine, follow these steps:

  1. Create an Google account (if you do not have any), and log in. Go to Google AppEngine and create a new application. Choose High Replication as the storage mode, and an Application Identifier of your preference.
  2. Prepare a clean working directory for the deployment:
    mkdir /home/user/fileshack
    cd /home/user/fileshack
  3. Download Google App Engine SDK for Python and unpack it into the working directory. Add it the PATH environment variable:
    export PATH="$PATH:/home/user/fileshack/google_appengine"
  4. Clone repositories from the django-nonrel project into the working directory:
    hg clone https://bitbucket.org/wkornewald/django-nonrel
    hg clone https://bitbucket.org/wkornewald/djangoappengine
    hg clone https://bitbucket.org/wkornewald/djangotoolbox
    hg clone https://bitbucket.org/twanschik/django-autoload
    hg clone https://bitbucket.org/wkornewald/django-dbindexer
    If you do not want to use mercurial (hg), you can download them from allbuttonspressed.com.
  5. Clone the appengine branch of fileshack into the working directory:
    git clone -b appengine git://github.com/peterkuma/fileshackproject.git
    cd fileshackproject
  6. Open app.yaml and set application: to the Application Identifier you chose when you created the application on Google AppEngine.
    vi app.yaml
  7. Copy and customize the local settings example file:
    cp fileshackproject/settings_local-example.py fileshackproject/settings_local.py
    vi fileshackproject/settings_local.py

    Normally, you do not need to modify anything except for ADMINS and uncommenting DEBUG = False once your installation works properly.

  8. Collect static files into the static directory:
    ./manage.py collectstatic --noinput
  9. Run server locally. Is everything OK?
    ./manage.py runserver
  10. Deploy! You will be asked for your Google Account login details in the process. The process will also create a new django superuser account (say yes when prompted).
    ./manage.py deploy
  11. Go to the django administration console at http://appidentifier.appspot.com/admin/, and log in with the superuser account. Create a new Store with an empty Path, empty Media, and Access code of your choice.
  12. Fileshack should now be accessible at http://appidentifier.appspot.com, and your Google administration console at http://appspot.com. If you encounter any problems, drop an e-mail to the mailing list at fileshack-general@lists.sourceforge.net.

Compatibility

Fileshack is known to work with at least the following browsers:

Drag & Drop and progress indication are not supported in all browsers.

Release Notes

Fileshack 0.9(25 June 2012)

  • Files are not read into memory in full, but uploaded by File.slice() if available. This greatly reduces memory footprint and improves performance when uploading large files.
  • It is now possible to upload multiple files at once.
  • Fixed handling of unicode characters in file names.
  • Sessions now last until the browser is closed.
  • Fixed error message in Opera on expired session.

Fileshack 0.8(27 April 2012)

  • Store watching.
  • Fixed HTTP 404 page.
  • Logout is now protected against CSRF.
  • Django 1.4 timezone support.

Fileshack 0.7(18 April 2012)

  • Fixed uploading to custom (non-default) stores.
  • Fixed enforcement of store size limit.
  • Fixed error dialog placement.
  • Improved uploading in IE. Items are now replaced in-place without a refresh, and errors are reported in the usual way via an error dialog.
  • Open stores with an empty access code are now allowed.

Fileshack 0.6(29 March 2012)

  • Fixed uploading in Safari 5 on Snow Leopard.
  • Fixed regression in IE and Firefox 3.5.
  • Tweaked style to better support small screens.

Fileshack 0.5(28 March 2012)

  • Fixed uploading in Firefox 3.5.
  • Fixed style in some legacy browsers.

Fileshack 0.4(27 March 2012)

  • Fixed upload indication in IE 8 and 9.
  • Fixed dropbox text in IE 7.
  • Fixed delete in IE 7 and 8.

Fileshack 0.3(26 March 2012)

  • Fixed upload by Drag & Drop in Safari.
  • Fixed dropbox text when Drag & Drop is not supported.

Fileshack 0.2(25 March 2012)

  • Support for Safari and IE6-9.

Fileshack 0.1(20 March 2012)

  • Initial release.

How does it work?

Fileshack uses one of the following methods of uploading a file, listed from the most sophisticated to the least sophisticated:

  1. XMLHttpRequest with File API. File is read into browser memory by FileReader and uploaded by chunks. During upload, chunk size is tuned so that an optimal upload time is achieved. If upload fails, it can be resumed by starting from the last uploaded chunk. File upload progress is show. This method is supported by Firefox, Google Chrome and Opera. However, as Opera does not support XMLHttpRequest.upload, upload progress is coarse (by chunks).
  2. XMLHttpRequest with FormData. File is upload in full by XMLHttpRequest.send(FormData). Resume of a failed upload is not supported. Upload progress is indicated. This method is chosen for browers not supporting File API, such as Safari.
  3. Submitting a hidden iframe. This is a trick allowing submitting a file without displaying a file input element. Click on the dropbox is delegated to a file input element inside a hidden iframe, in order to circumvent a security check in IE not allowing to submit a form when a click was delegated. No progress indication is supported. This method is supported by browsers such as IE8 and IE9.
  4. Explicit file input element. An input element is displayed inside the dropbox. This method is chosen for browsers such as IE7.

Contributing

You can contribute by reporting issues, forking or joining the project as a developer on github. Thank you!