Run it yourself
The whole app, on a machine of your own.
ImageStoria is source-available. If you are at home with Docker, you can run it yourself: one image and a database. It is free for your own photos and for any other non-commercial use.
Who it is for
People who would rather hold the keys.
The hosted service and the self-hosted app are the same app. Running it yourself means you look after the server, the updates and the backups. In return, nothing about your library is on anyone else's machine.
- You have a home server, a NAS that runs Docker, or a small rented machine.
- You have used a terminal and edited a settings file before.
- You want the files on your own disk, or in a bucket of your choosing.
- You are willing to keep your own backups.
If that list reads like a chore, the hosted service does the same job and we run it for you.
What you need
Docker, and somewhere to run it.
A machine
Any computer that stays on and runs Linux containers. The app needs no graphics card. Disk is the thing to plan for: every original is kept, and viewing copies are made beside it.
Docker with Compose
The app is one image and a Postgres database, started together by one Compose file. To reach it from outside your home, put a reverse proxy with HTTPS in front.
A GPU machine, if you like
Optional. A worker on a computer with an NVIDIA card writes captions, finds faces and makes search by meaning work. It can be a different machine from the server.
Quick start
Four commands.
Clone the source, copy the settings file, set two values in it, and start.
In .env set PUBLIC_URL to the address people will type, and POSTGRES_PASSWORD to a long password of your own. Every other setting has a default and is described in that file.
The first visit makes the owner. Open the address straight away and complete the setup screen, before anyone else can reach it. Whoever completes it owns the library.
$ git clone https://github.com/chazartco/imagestoria.git
$ cd imagestoria
$ cp .env.example .env
# open .env and set PUBLIC_URL and POSTGRES_PASSWORD
$ docker compose up -d --buildThen open the address you set as PUBLIC_URL. By default that is http://localhost:8080.
Where files live
On your disk, or in any bucket.
By default files are kept on local disk, in a Docker volume. Set STORAGE_DRIVER=s3 and they go to any S3-compatible bucket instead, such as DigitalOcean Spaces. Keep the bucket private. The app never makes a file public.
No server yet? A DigitalOcean Droplet runs it well: a machine of your own with Docker, a few minutes after you sign up. The links to DigitalOcean on this site are referral links. If you sign up through one, DigitalOcean gives us credit. It costs you nothing extra.
Either way the layout is the same, and plain. The original is the file exactly as it was uploaded. The other folders are copies that can be made again.
To bring in a folder of photos you already have, mount it read-only and run the import command. The folder itself is never changed.
originals/{year}/{month}/{item id}/{file name}
display/{year}/{month}/{item id}.webp long edge 1600 px
thumbs/{year}/{month}/{item id}.webp 360 px high
full/{year}/{month}/{item id}.webp only for HEIC, TIFF and the like
Updating
Pull, then build again.
$ git pull
$ docker compose up -d --buildChanges to the database are applied when the app starts. There is nothing else to run.
Backing up
Two things hold everything.
The files. Nothing in the app makes a second copy of them. Copy the volume somewhere else, or turn on versioning or replication for the bucket.
The database. Titles, tags, comments, stories, people and edits. Set BACKUP_SCHEDULE in .env and the app makes a compressed dump every night, encrypted if you give it a passphrase.
The licence, in plain words
Free to use. Not free to sell.
ImageStoria is published under the PolyForm Noncommercial License 1.0.0. You can read the source, run it and change it. That is source-available, which is not the same as open source: commercial use is kept back.
You may
- Run it for your own photos and your family's.
- Run it for a club, a school, a charity or research.
- Change it to suit you, and share your changes under the same terms.
You may not
- Sell it.
- Offer it to other people as a paid or hosted service.
- Use it in any other commercial way without a commercial licence.
This is a summary, and the licence itself is what counts. Read the full text. For a commercial licence, write to Chaz.Art & Co. Contact
Hosted or self-hosted
The same app, two ways to run it.
Neither is the better one. They suit different people.
| Hosted at imagestoria.com | Self-hosted | |
|---|---|---|
| Who runs the server | We do. You sign up and it is there. | You do. Your machine, your Docker, your reverse proxy. |
| Where the files live | In your own DigitalOcean Space. A Space is required. | On local disk, or in any S3-compatible bucket. |
| Where the database lives | On our servers, one database for each library. | On your machine. |
| Updates | Done for you. | You pull and rebuild when you choose. |
| Backups | The database is in our care. The files in your Space are yours to back up. | Both are yours to back up. The app can dump the database nightly. |
| Cost | The price on the pricing page, plus your Space at DigitalOcean. | No charge for the software in non-commercial use. You pay for the machine, the disk and your time. |
| Address | name.imagestoria.com | Any address you own. |
| Signing in | Email and password. | Email and password, OpenID Connect, or both. |
| Reading pictures | A worker of your own, or a cloud AI key. | A worker of your own. |
| Settings | The ones in the library's settings page. | All of them, in .env. |
| If something breaks | Write to us. | You fix it, with the README and the issues on GitHub. |
Read the source. Then run it.
The README covers every setting, the reverse proxy, sign-in with OpenID Connect, workers, importing a folder, and restoring a backup.