Skip to main content

readinglist

Project description

Readinglist
===========

*Reading List* is a service that aims to synchronize a list of articles URLs
between a set of devices owned by a same account.

|travis| |readthedocs|

.. |travis| image:: https://travis-ci.org/mozilla-services/readinglist.svg?branch=master
:target: https://travis-ci.org/mozilla-services/readinglist

.. |readthedocs| image:: https://readthedocs.org/projects/readinglist/badge/?version=latest
:target: http://readinglist.readthedocs.org/en/latest/
:alt: Documentation Status

API
===

* `Online documentation <http://readinglist.readthedocs.org/en/latest/>`_


Run locally
===========

*Reading List* is based on top of the `cliquet <https://cliquet.rtfd.org>`_ project, and
as such, please refer to cliquet's documentation for more details.


For development
---------------

By default, *Reading List* persists the records and internal cache in a PostgreSQL
database.

The default configuration will connect to the ``postgres`` database on
``localhost:5432``, with user/password ``postgres/``postgres``. See more details
below about installation and setup of PostgreSQL.

::

make serve


Using Docker
------------

*Reading List* uses `Docker Compose <http://docs.docker.com/compose/>`_, which takes
care of running and connecting PostgreSQL:

::

docker-compose up


Authentication
--------------

By default, *Reading List* relies on Firefox Account OAuth2 Bearer tokens to authenticate
users.

See `cliquet documentation <http://cliquet.readthedocs.org/en/latest/configuration.html#authentication>`_
to configure authentication options.


Install and setup PostgreSQL
============================

(*requires PostgreSQL 9.3 or higher*).


Using Docker
------------

::

docker run -e POSTGRES_PASSWORD=postgres -p 5434:5432 postgres


Linux
-----

On debian / ubuntu based systems:

::

apt-get install postgresql postgresql-contrib


By default, the ``postgres`` user has no password and can hence only connect
if ran by the ``postgres`` system user. The following command will assign it:

::

sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'postgres';"


OS X
----

Assuming `brew <http://brew.sh/>`_ is installed:

::

brew update
brew install postgresql

Create the initial database:

::

initdb /usr/local/var/postgres


Install libffi
==============

Linux
-----

On debian / ubuntu based systems::

apt-get install libffi-dev


OS X
----

Assuming `brew <http://brew.sh/>`_ is installed, libffi installation becomes:

::

brew install libffi pkg-config


Run tests
=========

::

make tests


Running in production
=====================

Recommended settings
--------------------

Most default setting values in the application code base are suitable for production.

But the set of settings mentionned below might deserve some review or adjustments:

::

cliquet.http_scheme = https
cliquet.batch_max_requests = 25
cliquet.delete_collection_enabled = false
cliquet.basic_auth_enabled = false
fxa-oauth.cache_ttl_seconds = 3600

:note:

For an exhaustive list of available settings and their default values,
refer to `cliquet source code <https://github.com/mozilla-services/cliquet/blob/93b94a4ce7f6d8788e2c00b609ec270c377851eb/cliquet/__init__.py#L34-L59>`_.



PostgreSQL setup
----------------

In production, it is wise to run the application with a dedicated database and
user.

::

postgres=# CREATE USER produser;
postgres=# CREATE DATABASE proddb OWNER produser;
CREATE DATABASE


On the first app run, the tables and objects are created. Currently, this process
requires superuser privileges (or a ``BackendError`` might occur).

Grant superuser temporarily:

::

postgres=# ALTER USER produser SUPERUSER;
ALTER ROLE

Run the application.

Revoke superuser privilege:

::

postgres=# ALTER USER produser NOSUPERUSER;
ALTER ROLE


:note:

Alternatively the SQL initialization files can be found in the
*cliquet* source code (``cliquet/cache/postgresql/schemal.sql`` and
``cliquet/storage/postgresql/schemal.sql``).

:warning:

Using a `connection pool <http://pgpool.net>`_ is highly recommended to
boost performances and bound memory usage (*work_mem per connection*).


Running with uWsgi
------------------

If you want to run the application using uWsgi, you can use
the provided **app.wsgi** file and this command::

uwsgi --ini config/readinglist.ini

You can tweak the uWsgi configuration in the ini file in
the dedicated **[uwsgi]** section.

If you are using a different ini file, you need to set
its path in the **READINGLIST_INI** environment variable.


Changelog
=========

This document describes changes between each past release.


1.1.0 (2015-03-18)
------------------

**Breaking changes**

* `cliquet.storage.postgresql` now uses UUID as record primary key (mozilla-services/cliquet#70)
* Settings ``cliquet.session_backend`` and ``cliquet.session_url`` were
renamed ``cliquet.cache_backend`` and ``cliquet.cache_url`` respectively.
* FxA user ids are not hashed anymore (mozilla-services/cliquet#82)
* Setting ``cliquet.retry_after`` was renamed ``cliquet.retry_after_seconds``
* OAuth2 redirect url now requires to be listed in
``fxa-oauth.webapp.authorized_domains`` (e.g. ``*.mozilla.com``)
* Batch are now limited to 25 requests by default (mozilla-services/cliquet#90)
* OAuth relier has been disabled by default (#193)

**New features**

* Every setting can be specified via an environment variable
(e.g. ``cliquet.storage_url`` with ``CLIQUET_STORAGE_URL``)
* Logging now relies on `structlog <http://structlog.org>`_ (mozilla-services/cliquet#78)
* Logging output can be configured to stream JSON (mozilla-services/cliquet#78)
* New cache backend for PostgreSQL (mozilla-services/cliquet#44)
* Documentation was improved on various aspects (mozilla-services/cliquet#64, mozilla-services/cliquet#86)
* Handle every backend errors and return 503 errors (mozilla-services/cliquet#21)
* State verification for OAuth2 dance now expires after 1 hour (mozilla-services/cliquet#83)
* Add the preview field for an article (#156)
* Setup the readinglist OAuth scope (#16)
* Add a uwsgi file (#180)

**Bug fixes**

* FxA OAuth views errors are now JSON formatted (mozilla-services/cliquet#67)
* Prevent error when pagination token has bad format (mozilla-services/cliquet#72)
* List of CORS exposed headers were fixed in POST on collection (mozilla-services/cliquet#54)
* Fix environment variables not overriding configuration (mozilla-services/cliquet#100)
* Got rid of custom *CAST* in PostgreSQL storage backend to prevent installation
errors without superuser (ref #174, mozilla-services/cliquet#99)


1.0 (2015-03-03)
----------------

**Breaking changes**

- Most configuration entries were renamed, see `config/readinglist.ini`
example to port your configuration
- Status field was removed, archived and deleted fields were added
(requires a database flush.)
- Remove Python 2.6 support

**New features**

- Add the /fxa-oauth/params endpoint
- Add the DELETE /articles endpoint
(Needs cliquet.delete_collection_enabled configuration)
- Add the Response-Behavior header on PATCH /articles
- Add HTTP requests / responses examples in the documentation
- Use Postgresql as the default database backend

**Internal changes**

- Main code base was split into a separate project
`Cliquet <https://github.com/mozilla-services/cliquet>`_
- Perform continuated pagination in loadtests
- Use PostgreSQL for loadtests


0.2.2 (2015-02-13)
------------------

**Bug fixes**

- Fix CORS preflight request permissions (PR #119)


0.2.1 (2015-02-11)
------------------

**Breaking changes**

- Internal user ids for FxA are now prefixed, all existing records
will be lost (refs #109)

**Bug fixes**

- Fix CORS headers on validation error responses (ref #104)
- Fix handling of defaults in batch requests (ref #111, #112)


0.2 (2015-02-09)
----------------

**Breaking changes**

- PUT endpoint was disabled (ref #42)
- ``_id`` field was renamed to ``id`` (ref PR #91)
- FxA now requires a redirection URL (ref PR #69)

**New features**

- URLs uniques by user (ref #20)
- Handle conflicts responses (ref #45)
- Conditional changes for some articles attributes (ref #6)
- Batching support (ref #2)
- Pagination support (ref #25)
- Online documentation available at http://readinglist.readthedocs.org (ref PR #73)
- Basic Auth nows support any user/password combination (ref PR #78)

**Bug fixes**

- ``marked_read_by`` was ignored on PATCH (ref PR #72)
- Timestamp was not incremented on DELETE (ref PR #95)
- Fix number of bugs regarding support of CORS in error views (ref PR #105)
- Previous Basic Auth could impersonate FxA user (ref PR #78)


0.1 (2015-01-30)
----------------

- Allow Cors (#67)
- Log incomming request to the console (#65)
- Add timestamp for 304 and 412 response (#40)
- Add time vector to GET /articles and GET /articles/<id> (#4)
- Preconditions Headers for Update and Creation (#60)
- Provide number of items in headers of GET /articles (#39)
- Check for filter values (#58)
- Handle article title length (#37)
- Support min, max and no keywords filters (#43)
- Prevent to modify read-only fields (#26)
- Filtering and sort querystring (#44)
- Redis storage (#50)
- Handle errors (#24 - #49)
- Add loadtests (#47)
- Handle API version in URL (#33)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for readinglist, version 1.1.0
Filename, size File type Python version Upload date Hashes
Filename, size readinglist-1.1.0.tar.gz (16.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page