jiaoge

Keeping track of postcards if you're into it

Quickstart

Requirements

• Heroku account (free tier is good as well).
• Amazon Web Services account (free tier works here too).
  • S3 bucket, not exposed to the public by default.
  • IAM credentials for non-root user.

Setup

1. Create a new application on Heroku, use the newest stack (heroku-18).
2. Add Heroku Postgres add-on (Hobby Dev suffices).
3. Add Sentry add-on if you want to track errors.
4. Add heroku/python buildpack.
5. Add heroku-community/apt buildpack.
6. Connect your (clone of this one) Github repository to your Heroku app.
7. Set the Config Vars.
   • ADMIN_URL -- generate some hard to guess string in a form of foo/.
   • AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY -- your IAM credentials.
   • AWS_STORAGE_BUCKET_NAME -- name of your S3 bucket.
   • HASHID_FIELD_SALT -- generate another hard to guess long string.
   • HEROKU_DOMAIN -- the domain you access the app at. e.g.: myproject.herokuapp.com.

First run

1. Use the Manual deploy feature on Heroku to deploy master branch.
2. Wait until the deployment is done.
3. Select a Free dyno tier for the web dyno.
4. Enable the web dyno to start it.
5. Spawn a shell session for the app: heroku run -a <your app name> bash
6. Push the static files to S3: ./manage.py collectstatic.

Why

I personally send a lot of postcards to my family and friends whenever I'm traveling.

One day it hit me -- it would be really nice to keep track which postcard did I send to whom from where. On top of that, if only I could tell how long have the postcards spent in transit?

I built this project as minimal, simple way to make this happen.

The whole application can be easily deployed on free Heroku tier. It relies on PostgreSQL instance being running and attached to the app.

What

This is a very basic Django-based web application with barely any front-end code, mostly leveraging the awesome Django Admin system.

Normalize and Milligram CSS framework are used to make the few server-rendered views to look semi-decent on both desktop and mobile devices.

There's absolutely no JavaScript code involved.

How

One can use the admin pages to create a simple "address book" (actually more of a rolodex as I wanted to avoid storing addresses) of friends and family members.

As a second step it's possible to create records for the postcards to be sent from one's travels. A card record is very rudimentary and consists of the postcard source (where was it posted), destination (selected contact from the address book) and dispatch date.

An extra feature allows user to upload a picture of the postcard to be attached to the card record.

In a basic form the application user can also edit the card records to append the information about the time of postcard reception.

Bonus: interactivity

The cherry on top is the ability for the postcard receivers to confirm their arrival (claim the card).

There's a card claim view: /claim/<CODE> that can be used by the addressee to let the sender know about the reception with a single press of a button. Naturally, this relies on your friends/family being bothered enough to actually open the claiming URL.

You can write/print the URL on your postcards to let the addressees enter the claim page. I personally use TinyURL to shorten the long Heroku address.

I also researched and opted for standard-format (48.5mm × 16.9mm) stickers with pre-printed shortened claim URL, to which I add (by hand) the card claim code (generated by the great hashids library). Every postcard has an unique claim address and can only be claimed once (naturally). Finally I let the received give me a comment/feedback before clicking the button.