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)
===========
*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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
readinglist-1.1.0.tar.gz
(16.4 kB
view hashes)