Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/onyxfish/pixelcite

Pixelcite: Quotations for Twitter
https://github.com/onyxfish/pixelcite

Last synced: about 1 month ago
JSON representation

Pixelcite: Quotations for Twitter

Awesome Lists containing this project

README 

        
pixelcite

========================



* [What is this?](#what-is-this)

* [What's in here?](#whats-in-here)

* [Bootstrap the project](#bootstrap-the-project)

* [Hide project secrets](#hide-project-secrets)

* [Save media assets](#save-media-assets)

* [Run the project](#run-the-project)

* [COPY editing](#copy-editing)

* [Compile static assets](#compile-static-assets)

* [Test the rendered app](#test-the-rendered-app)

* [Deploy to S3 and EC2](#deploy-to-s3-and-ec2)

* [Install web services](#install-web-services)

* [Run a remote fab command](#run-a-remote-fab-command)

* [Report analytics](#report-analytics)



What is this?

-------------



Quotations for Twitter.



This project is based on the [NPR app-template](https://github.com/nprapps/app-template).



What's in here?

---------------



The project contains the following folders and important files:



* ``confs`` -- Server configuration files for nginx and uwsgi. Edit the templates then ``fab  servers.render_confs``, don't edit anything in ``confs/rendered`` directly.

* ``data`` -- Data files, such as those used to generate HTML.

* ``fabfile`` -- [Fabric](http://docs.fabfile.org/en/latest/) commands for automating setup, deployment, data processing, etc.

* ``etc`` -- Miscellaneous scripts and metadata for project bootstrapping.

* ``jst`` -- Javascript ([Underscore.js](http://documentcloud.github.com/underscore/#template)) templates.

* ``less`` -- [LESS](http://lesscss.org/) files, will be compiled to CSS and concatenated for deployment.

* ``templates`` -- HTML ([Jinja2](http://jinja.pocoo.org/docs/)) templates, to be compiled locally.

* ``www`` -- Static and compiled assets to be deployed. (a.k.a. "the output")

* ``www/assets`` -- A symlink to an S3 bucket containing binary assets (images, audio).

* ``app.py`` -- A [Flask](http://flask.pocoo.org/) app for rendering the project locally.

* ``app_config.py`` -- Global project configuration for scripts, deployment, etc.

* ``copytext.py`` -- Code supporting the [Editing workflow](#editing-workflow)

* ``crontab`` -- Cron jobs to be installed as part of the project.

* ``public_app.py`` -- A [Flask](http://flask.pocoo.org/) app for running server-side code.

* ``render_utils.py`` -- Code supporting template rendering.

* ``requirements.txt`` -- Python requirements.

* ``static.py`` -- Static Flask views used in both ``app.py`` and ``public_app.py``.



Bootstrap the project

---------------------



Node.js is required for the static asset pipeline. If you don't already have it, get it like this:



```

brew install node

curl https://npmjs.org/install.sh | sh

```



Then bootstrap the project:



```

cd pixelcite

mkvirtualenv --no-site-packages pixelcite

pip install -r requirements.txt

npm install

fab update

```



**Problems installing requirements?** You may need to run the pip command as ``ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install -r requirements.txt`` to work around an issue with OSX.



Hide project secrets

--------------------



Project secrets should **never** be stored in ``app_config.py`` or anywhere else in the repository. They will be leaked to the client if you do. Instead, always store passwords, keys, etc. in environment variables and document that they are needed here in the README.



Save media assets

-----------------



Large media assets (images, videos, audio) are synced with an Amazon S3 bucket specified in ``app_config.ASSETS_S3_BUCKET`` in a folder with the name of the project. (This bucket should not be the same as any of your ``app_config.PRODUCTION_S3_BUCKETS`` or ``app_config.STAGING_S3_BUCKETS``.) This allows everyone who works on the project to access these assets without storing them in the repo, giving us faster clone times and the ability to open source our work.



Syncing these assets requires running a couple different commands at the right times. When you create new assets or make changes to current assets that need to get uploaded to the server, run ```fab assets.sync```. This will do a few things:



* If there is an asset on S3 that does not exist on your local filesystem it will be downloaded.

* If there is an asset on that exists on your local filesystem but not on S3, you will be prompted to either upload (type "u") OR delete (type "d") your local copy.

* You can also upload all local files (type "la") or delete all local files (type "da"). Type "c" to cancel if you aren't sure what to do.

* If both you and the server have an asset and they are the same, it will be skipped.

* If both you and the server have an asset and they are different, you will be prompted to take either the remote version (type "r") or the local version (type "l").

* You can also take all remote versions (type "ra") or all local versions (type "la"). Type "c" to cancel if you aren't sure what to do.



Unfortunantely, there is no automatic way to know when a file has been intentionally deleted from the server or your local directory. When you want to simultaneously remove a file from the server and your local environment (i.e. it is not needed in the project any longer), run ```fab assets.rm:"www/assets/file_name_here.jpg"```



Run the project

---------------



A flask app is used to run the project locally. It will automatically recompile templates and assets on demand.



```

workon $PROJECT_SLUG

python public_app.py

```



Visit [localhost:8000](http://localhost:8000) in your browser.



COPY editing

------------



This app uses a Google Spreadsheet for a simple key/value store that provides an editing workflow.



View the [sample copy spreadsheet](https://docs.google.com/spreadsheet/pub?key=0AlXMOHKxzQVRdHZuX1UycXplRlBfLVB0UVNldHJYZmc#gid=0).



This document is specified in ``app_config`` with the variable ``COPY_GOOGLE_DOC_KEY``. To use your own spreadsheet, change this value to reflect your document's key (found in the Google Docs URL after ``&key=``).



A few things to note:



* If there is a column called ``key``, there is expected to be a column called ``value`` and rows will be accessed in templates as key/value pairs

* Rows may also be accessed in templates by row index using iterators (see below)

* You may have any number of worksheets

* This document must be "published to the web" using Google Docs' interface



The app template is outfitted with a few ``fab`` utility functions that make pulling changes and updating your local data easy.



To update the latest document, simply run:



```

fab copytext.update 

```



Note: ``copytext.update`` runs automatically whenever ``fab render`` is called.



At the template level, Jinja maintains a ``COPY`` object that you can use to access your values in the templates. Using our example sheet, to use the ``byline`` key in ``templates/index.html``:



```

{{ COPY.attribution.byline }}

```



More generally, you can access anything defined in your Google Doc like so:



```

{{ COPY.sheet_name.key_name }}

```



You may also access rows using iterators. In this case, the column headers of the spreadsheet become keys and the row cells values. For example:



```

{% for row in COPY.sheet_name %}

{{ row.column_one_header }}

{{ row.column_two_header }}

{% endfor %}

```



When naming keys in the COPY document, pleaseattempt to group them by common prefixes and order them by appearance on the page. For instance:



```

title

byline

about_header

about_body

about_url

download_label

download_url

```



Compile static assets

---------------------



Compile LESS to CSS, compile javascript templates to Javascript and minify all assets:



```

workon pixelcite

fab render

```



(This is done automatically whenever you deploy to S3.)



Test the rendered app

---------------------



If you want to test the app once you've rendered it out, just use the Python webserver:



```

cd www

python -m SimpleHTTPServer

```



Deploy to S3 and EC2

--------------------



```

fab staging master deploy

```



Install web services

---------------------



Web services are configured in the `confs/` folder.



To check that these files are being properly rendered, you can render them locally and see the results in the `confs/rendered/` directory.



```

fab servers.render_confs

```



You can also deploy only configuration files by running (normally this is invoked by `deploy`):



```

fab servers.deploy_confs

```



Run a  remote fab command

-------------------------



Sometimes it makes sense to run a fabric command on the server, for instance, when you need to render using a production database. You can do this with the `fabcast` fabric command. For example:



```

fab staging master servers.fabcast:deploy

```



If any of the commands you run themselves require executing on the server, the server will SSH into itself to run them.



Analytics

---------



The Google Analytics events tracked in this application are:



|Category|Action|Label|Value|Custom 1|Custom 2|

|--------|------|-----|-----|--------|--------|

|pixelcite|tweet|||||

|pixelcite|save-image|||||

|pixelcite|login|||||