Simplesnap is a node.js application that allows you to host your own image upload service. It features an embedded webserver that accepts POST and PUT requests to upload images, renames the images to a short hashed string, and serves the images. Uploads may include an expiration field, to indicate that after a certain time the image will be deleted. Image records and API keys are stored in a database (sqlite3 by default, but can use MySQL and Postgres). Bash scripts are provided for uploading and managing images. It does not have a human-facing interface for uploads or image management.
There are already a plethora of image hosts out there, so why did I write my own?
- I wanted a service that's simple. I don't want to deal with OAuth and complicated APIs, I just want a service that I can
POSTan image to. - I wanted a service that doesn't re-encode images. Imgur is especially bad about re-encoding large images with lossy formats. With simplesnap, I can mandate my own file size limits and preserve the original image format.
- I wanted a service with easy expiration management. I often take screenshots to share a quick look at something to a friend. I don't want these images to be floating around the internet forever, nor do I want to be tasked with remembering to delete them. With simlpesnap, I can choose an appropriate expiration and forget about it.
- I wanted control of my own images. I know exactly what happens when I'm uploading an image to simplesnap
You will need Linux and node.js. If you plan to run the server on Debian or Ubuntu, install node.js from source or from the NodeSource repositories to ensure you have a version of node that's not several years old. In addition, you must have a C compiler installed to build some of the dependencies.
- Clone the repository (
git clone https://github.com/calzoneman/simplesnap) - Change to the
simplesnapdirectory and runnpm install - Copy
config.template.jstoconfig.jsand make any modifications you would like to the configuration - Run the server with
node index.js
npm breaks if python is Python 3, and is not smart enough to guess that the Python 2 interpreter might be named python2. Set the $PYTHON environment variable before running npm install:
$ PYTHON=python2 npm install
Simplesnap uses knex, which abstracts the database logic from the underlying database driver. If you wish to use MySQL/MariaDB or Postgres instead of SQLite3, edit the configuration in config.js accordingly and install the appropriate node driver:
$ npm install mysql
$ npm install pg
Run the following:
$ npm install nedb
$ node lib/migrate-0.0.1-1.0.js
After running these commands, verify that the import is correct (perhaps by opening snap.sqlite and examining the records in the images table). After verifying such, it is safe to remove images.db, accounts.db, and node_modules/nedb.
Unless you have set config.allowAnonymousUploads = true, you will be unable to upload images without a x-simplesnap-auth key. To generate one, pass the --adduser or -a flag:
$ node index.js --adduser
Database initialized
Created user {"key":"RXubxRIiR2SzuaThcBTkXQ==","created_at":"2014-11-08T19:40:16.154Z","id":3}
If you are using the provided bash scripts for image management, you would then write your key into ~/.simplesnap_key so the scripts can read it:
$ echo "RXubxRIiR2SzuaThcBTkXQ==" > ~/.simplesnap_key
You can list your user keys with --listusers or -l:
$ node index.js --listusers
Database initialized
{"id":3,"key":"RXubxRIiR2SzuaThcBTkXQ==","created_at":1415475616154}
You can revoke a user key with --revokeuser or -r:
$ node index.js --revokeuser RXubxRIiR2SzuaThcBTkXQ==
Database initialized
Deleted user RXubxRIiR2SzuaThcBTkXQ==
Note: When you revoke a user, it does not delete images uploaded by that user. Instead, the user_key field becomes NULL for such images (as if they were uploaded anonymously). There is not currently a way to delete the images other than manually running database queries to delete the images with that user_key and then deleting the user afterwards.
A few useful scripts are included in bin/ that allow you to upload, list, and delete images on your simplesnap server. The API is quite simple, so you could easily write your own tools to do the same.
Before using the client scripts, you'll need to replace the SERVER variable with the hostname and port that simplesnap is running on. For example:
$ cd bin
$ sed -i 's/localhost:5000/mycooldomain.com/' simplesnap-*
I recommend adding the full path to simplesnap/bin to your $PATH for convenience. These scripts expect your simplesnap authentication key to be in ~/.simplesnap-key.
Usage:
$ simplesnap-upload /path/to/file.png
This script uses curl to make a POST request to upload a file to your simplesnap server. When the request is complete, it uses notify-send to send a message notifying you that the upload suceeded or failed. If it succeeded, the resulting image URL is copied to the clipboard with xclip.
Usage:
$ simplesnap-list
This script lists all non-expired images uploaded with your authentication key.
Usage:
$ simplesnap-delete http://mycooldomain.com/somefile.png
This script makes a DELETE request for an image uploaded using your authentication key. If the image exists and is not expired, the server will delete the image and database record.
If you are running simplesnap behind a reverse proxy (I use nginx), make sure the Host header is set properly by the proxy or else the links returned by /upload will contain 127.0.0.1 (or whatever address the proxy is configured to connect to) instead of the correct hostname.
If you need help, feel free to email cyzon [at] cyzon [dot] us with questions. You can also find me on the following IRC networks with the nickname calzoneman: irc.esper.net, irc.netchat.io, irc.6irc.net.
For bugs and feature requests, please open a GitHub issue. Pull requests are welcome, but please try to keep things simple.
simplesnap is released under the MIT license. See the LICENSE file for details.