diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 7 | ||||
| -rw-r--r-- | docs/source/api/activities.rst | 208 | ||||
| -rw-r--r-- | docs/source/api/authentication.rst (renamed from docs/source/api/client_register.rst) | 67 | ||||
| -rw-r--r-- | docs/source/api/media.rst | 155 | ||||
| -rw-r--r-- | docs/source/api/media_interaction.rst | 65 | ||||
| -rw-r--r-- | docs/source/api/oauth.rst | 36 | ||||
| -rw-r--r-- | docs/source/api/objects.rst | 229 | ||||
| -rw-r--r-- | docs/source/conf.py | 4 | ||||
| -rw-r--r-- | docs/source/index.rst | 9 | ||||
| -rw-r--r-- | docs/source/plugindocs/oauth.rst | 1 | ||||
| -rw-r--r-- | docs/source/pluginwriter/api.rst | 2 | ||||
| -rw-r--r-- | docs/source/siteadmin/configuration.rst | 28 | ||||
| -rw-r--r-- | docs/source/siteadmin/deploying.rst | 144 | ||||
| -rw-r--r-- | docs/source/siteadmin/media-types.rst | 19 | ||||
| -rw-r--r-- | docs/source/siteadmin/relnotes.rst | 11 |
15 files changed, 625 insertions, 360 deletions
diff --git a/docs/Makefile b/docs/Makefile index 0b97bf7c..e9ee5af0 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,6 +2,7 @@ # # You can set these variables from the command line. +PYTHON ?= python SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = @@ -14,11 +15,12 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext +.PHONY: help clean html htmlview dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make <target>' where <target> is one of" @echo " html to make standalone HTML files" + @echo " htmlview to open the index page built by the html target in your browser" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @@ -46,6 +48,9 @@ html: @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." +htmlview: html + $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')" + dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo diff --git a/docs/source/api/activities.rst b/docs/source/api/activities.rst new file mode 100644 index 00000000..cbbd1fab --- /dev/null +++ b/docs/source/api/activities.rst @@ -0,0 +1,208 @@ +.. MediaGoblin Documentation + + Written in 2015 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + <http://creativecommons.org/publicdomain/zero/1.0/>. + +========== +Activities +========== + +.. contents:: Sections + :local: + +GNU MediaGoblin uses `Activity Streams 1.0 <http://activitystrea.ms>`_ JSON +format to represent activities or events that happen. There are several +components to Activity Streams. + +Objects +======= +These represent "things" in MediaGoblin such as types of media, comments, collections +of other objects, etc. There are attributes all objects have and some attributes which +are specific to certain objects. + +Example +------- +a representation of an image object:: + + { + "id": "https://gmg.server.tld/api/image/someidhere", + "objectType": "image", + "content": "My lovely image", + "image": { + "url": "https://gmg.server.tld/mgoblin_media/media_entries/23/some_image.jpg", + "height": 1000, + "width": 500 + }, + "author": { + "id": "acct:someone@gmg.server.tld" + } + } + +This has both attributes which are on all objects (e.g. ``objectType`` and ``id``) +and attributes which are on only images (e.g. ``image``). + +Activities +========== +This is something which happens such as: commenting on an image, uploading an image, etc. +these always have a ``verb`` which describes what kind of activity it is and they always have +an ``object`` associated with them. + +Example +------- +A activity which describes the event of posting a new image:: + + { + "id": "https://gmg.server.tld/api/activity/someidhere", + "verb": "post", + "object": { + "id": "https://gmg.server.tld/api/comment/someid", + "objectType": "comment", + "content": "What a wonderful picture you have there!", + "inReplyTo": { + "id": "https://gmg.server.tld/api/image/someidhere" + } + }, + "author": { + "id": "acct:someone@gmg.server.tld" + } + } + +Collections +=========== + +These are ordered lists which contain objects. Currently in GNU MediaGoblin they are used +to represent "albums" or collections of media however they can represent anything. They will +be used in the future to represent lists/groups of users which you can send activities to. + +Example +^^^^^^^ +A collection which contains two images:: + + { + "id": "https://gmg.server.tld/api/collection/someidhere", + "totalItems": 2, + "url": "http://gmg.server.tld/u/someone/collection/cool-album/", + "items": [ + { + "id": "https://gmg.server.tld/api/image/someidhere", + "objectType": "image", + "content": "My lovely image", + "image": { + "url": "https://gmg.server.tld/mgoblin_media/media_entries/23/some_image.jpg", + "height": 1000, + "width": 500 + }, + "author": { + "id": "acct:someone@gmg.server.tld" + } + }, + { + "id": "https://gmg.server.tld/api/image/someother", + "objectType": "image", + "content": "Another image for you", + "image": { + "url": "https://gmg.server.tld/mgoblin_media/media_entries/24/some_other_image.jpg", + "height": 1000, + "width": 500 + }, + "author": { + "id": "acct:someone@gmg.server.tld" + } + } + ] + } + +Feeds +----- + +There are several feeds which can be read and posted to as part of the API. Some +of the feeds are still a work in progress however a lot of them are present for +compatibility. + +They also support certain GET parameters which allow you to control the stream. +These are: + ++-------------+----------+----------+----------------------------------+ +| Parameter | Default | Limit | Description | ++=============+==========+==========+==================================+ +| count | 20 | 200 | Number of activities to return | ++-------------+----------+----------+----------------------------------+ +| offset | 0 | No limit | Offset of collection | ++-------------+----------+----------+----------------------------------+ + +.. warning:: + Activities are added to the beginning of collection so using count and + offset is a bad way of doing pages. + +.. important:: + Due to the way we're currently doing deletes in MediaGoblin some activities + are broken and are skipped. This means the number you specify in the count + is NOT always the number of activities returned. + + +Inbox +^^^^^ + +**Endpoint:** `/api/user/<username>/inbox` + +This feed can be read by user to see what media has been sent to them. +MediaGoblin currently doesn't have the ability to sent media to anyone +as all media is public, all media on that instance should show up in the +users inbox. + +There are also subsets of the inbox which are: + +Major +""""" +**Endpoint:** ``/api/user/<username>/inbox/major`` + +This contains all major changes such as new objects being posted. Currently +comments exist in this feed, in the future they will be moved to the minor feed. + +Minor +""""" +**Endpoint:** ``/api/user/<username>/inbox/minor`` + +This contains minor changes such as objects being updated or deleted. This feed +should have comments in it, currently they are listed under major, in the future +they will exist in this endpoint. + +Direct +"""""" +**Endpoint:** ``/api/user/<username>/inbox/direct`` + +Currently this is just a mirror of the regular inbox for compatibility with +pump.io. In the future this will contain all objects specifically addressed to +the user. + +Direct major +"""""""""""" +**Endpoint:** ``/api/user/<username>/inbox/direct/major`` + +Currently this is just a mirror of the major inbox for compatibility with +pump.io. In the future this will contain all major activities which are +specifically addressed to the user. + +Direct minor +"""""""""""" +**Endpoint:** ``/api/user/<username>/inbox/direct/minor`` + +Currently this is just a mirror of the minor inbox for compatibility with +pump.io. In the future this will contain all minor activities which are +specifically addressed to the user. + +Feed (outbox) +^^^^^^^^^^^^^ +**Endpoint:** ``/api/user/<username>/feed`` + +This is where the client should post new activities. It can be read by the +user to see what they have posted. This will only contain content they have +authored or shared (sharing will come in the future). diff --git a/docs/source/api/client_register.rst b/docs/source/api/authentication.rst index 08f92c47..1d52d300 100644 --- a/docs/source/api/client_register.rst +++ b/docs/source/api/authentication.rst @@ -1,6 +1,6 @@ .. MediaGoblin Documentation - Written in 2011, 2012 by MediaGoblin contributors + Written in 2015 by MediaGoblin contributors To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this software to @@ -11,11 +11,17 @@ Dedication along with this software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>. -==================== +================== +API Authentication +================== + +.. contents:: Sections + :local: + Registering a Client ==================== -To use the GNU MediaGoblin API you need to use the dynamic client registration. This has been adapted from the `OpenID specification <https://openid.net/specs/openid-connect-registration-1_0.html>`_, this is the only part of OpenID that is being used to serve the purpose to provide the client registration which is used in OAuth. +To use the GNU MediaGoblin API you need to use the dynamic client registration. This has been adapted from the `OpenID specification <https://openid.net/specs/openid-connect-registration-1_0.html>`_, this is the only part of OpenID that is being used to serve the purpose to provide the client registration which is used in OAuth. The endpoint is ``/api/client/register`` @@ -31,7 +37,7 @@ client_secret **update only** - This should only be used updating client information, this is the client_secret given when you register contacts - **optional** - This a space seporated list of email addresses to contact of people responsible for the client + **optional** - This a space separated list of email addresses to contact of people responsible for the client application_type **required** - This is the type of client you are making, this must be either *web* or *native* @@ -39,15 +45,15 @@ application_type application_name **optional** - This is the name of your client -logo_url - **optional** - This is a URL of the logo image for your client +logo_uri + **optional** - This is a URI of the logo image for your client redirect_uri - **optional** - This is a space seporated list of pre-registered URLs for use at the Authorization Server + **optional** - This is a space separated list of pre-registered URLs for use at the Authentication Server Response --------- +^^^^^^^^ You will get back a response: @@ -60,12 +66,11 @@ client_secret expires_at This is time that the client credentials expire. If this is 0 the client registration does not expire. -======= -Example -======= +Examples +-------- Register Client ---------------- +^^^^^^^^^^^^^^^ To register a client for the first time, this is the minimum you must supply:: @@ -84,7 +89,7 @@ A Response will look like:: Updating Client ---------------- +^^^^^^^^^^^^^^^ Using the response we got above we can update the information and add new information we may have opted not to supply:: @@ -93,8 +98,8 @@ Using the response we got above we can update the information and add new inform "client_id": "vwljdhUMhhNbdKizpjZlxv", "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb", "application_type": "web", - "application_name": "MyClient!", - "logo_url": "https://myclient.org/images/my_logo.png", + "application_name": "MyClient!", + "logo_uri": "https://myclient.org/images/my_logo.png", "contacts": "myemail@someprovider.com another_developer@provider.net", } @@ -107,9 +112,8 @@ The response will just return back the client_id and client_secret you sent:: } -====== -Errors -====== +Possible Registration Errors +---------------------------- There are a number of errors you could get back, This explains what could cause some of them: @@ -129,7 +133,7 @@ client_id is required to update. When you try and update you need to specify the client_id, this will be what you were given when you initially registered the client. client_secret is required to update. - When you try to update you need to specify the client_secrer, this will be what you were given when you initially register the client. + When you try to update you need to specify the client_secret, this will be what you were given when you initially register the client. Unauthorized. This is when you are trying to update however the client_id and/or client_secret you have submitted are incorrect. @@ -144,15 +148,34 @@ Logo URL <url> is not a valid URL This is when the URL specified did not meet the validation. contacts must be a string of space-separated email addresses. - ``contacts`` should be a string (not a list), ensure each email is seporated by a space + ``contacts`` should be a string (not a list), ensure each email is separated by a space Email <email> is not a valid email This is when you have submitted an invalid email address redirect_uris must be space-separated URLs. - ``redirect_uris`` should be a string (not a list), ensure each URL is seporated by a space + ``redirect_uris`` should be a string (not a list), ensure each URL is separated by a space URI <URI> is not a valid URI This is when your URI is invalid. - +OAuth +===== + +GNU MediaGoblin uses OAuth1 to authenticate requests to the API. There are many +libraries out there for OAuth1, you're likely not going to have to do much. There +is a library for the GNU MediaGoblin called `PyPump <https://github.com/xray7224/PyPump>`_. +We are not using OAuth2 as we want to stay completely compatible with pump.io. + + +Endpoints +--------- + +These are the endpoints you need to use for the oauth requests: + +`/oauth/request_token` is for getting the request token. + +`/oauth/authorize` is to send the user to to authorize your application. + +`/oauth/access_token` is for getting the access token to use in requests. + diff --git a/docs/source/api/media.rst b/docs/source/api/media.rst deleted file mode 100644 index bafe43d3..00000000 --- a/docs/source/api/media.rst +++ /dev/null @@ -1,155 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - <http://creativecommons.org/publicdomain/zero/1.0/>. - -.. info:: Currently only image uploading is supported. - -=============== -Uploading Media -=============== - -To use any the APIs mentioned in this document you will required :doc:`oauth` - -Uploading and posting an media requiest you to make two to three requests: - -1) Uploads the data to the server -2) Post media to feed -3) Update media to have title, description, license, etc. (optional) - -These steps could be condenced in the future however currently this is how the -pump.io API works. There is currently an issue open, if you would like to change -how this works please contribute upstream: https://github.com/e14n/pump.io/issues/657 - ----------------------- -Upload Media to Server ----------------------- - -To upload media you should use the URI `/api/user/<username>/uploads`. - -A POST request should be made to the media upload URI submitting at least two header: - -* `Content-Type` - This being a valid mimetype for the media. -* `Content-Length` - size in bytes of the media. - -The media data should be submitted as POST data to the image upload URI. -You will get back a JSON encoded response which will look similiar to:: - - { - "updated": "2014-01-11T09:45:48Z", - "links": { - "self": { - "href": "https://<server>/image/4wiBUV1HT8GRqseyvX8m-w" - } - }, - "fullImage": { - "url": "https://<server>//uploads/<username>/2014/1/11/V3cBMw.jpg", - "width": 505, - "height": 600 - }, - "replies": { - "url": "https://<server>//api/image/4wiBUV1HT8GRqseyvX8m-w/replies" - }, - "image": { - "url": "https://<server>/uploads/<username>/2014/1/11/V3cBMw_thumb.jpg", - "width": 269, - "height": 320 - }, - "author": { - "preferredUsername": "<username>", - "displayName": "<username>", - "links": { - "activity-outbox": { - "href": "https://<server>/api/user/<username>/feed" - }, - "self": { - "href": "https://<server>/api/user/<username>/profile" - }, - "activity-inbox": { - "href": "https://<server>/api/user/<username>/inbox" - } - }, - "url": "https://<server>/<username>", - "updated": "2013-08-14T10:01:21Z", - "id": "acct:<username>@<server>", - "objectType": "person" - }, - "url": "https://<server>/<username>/image/4wiBUV1HT8GRqseyvX8m-w", - "published": "2014-01-11T09:45:48Z", - "id": "https://<server>/api/image/4wiBUV1HT8GRqseyvX8m-w", - "objectType": "image" - } - -The main things in this response is `fullImage` which contains `url` (the URL -of the original image - i.e. fullsize) and `image` which contains `url` (the URL -of a thumbnail version). - -.. warning:: Media which have been uploaded but not submitted to a feed will - periodically be deleted. - --------------- -Submit to feed --------------- - -This is submitting the media to appear on the website. This will create an -object in your feed which will then appear on the GNU MediaGoblin website so the -user and others can view and interact with the media. - -The URL you need to POST to is `/api/user/<username>/feed` - -You first should do a post to the feed URI with some of the information you got -back from the above request (which uploaded the media). The request should look -something like:: - - { - "verb": "post", - "object": { - "id": "https://<server>/api/image/6_K9m-2NQFi37je845c83w", - "objectType": "image" - } - } - -.. warning:: Any other data submitted **will** be ignored - -------------------- -Submitting Metadata -------------------- - -Finally if you wish to set a title, description and license you will need to do -and update request to the endpoint, the following attributes can be submitted: - -+--------------+---------------------------------------+-------------------+ -| Name | Description | Required/Optional | -+==============+=======================================+===================+ -| displayName | This is the title for the media | Optional | -+--------------+---------------------------------------+-------------------+ -| content | This is the description for the media | Optional | -+--------------+---------------------------------------+-------------------+ -| license | This is the license to be used | Optional | -+--------------+---------------------------------------+-------------------+ - -.. note:: license attribute is mediagoblin specific, pump.io does not support this attribute - - -The update request should look something similiar to:: - - { - "verb": "update", - "object": { - "displayName": "My super awesome image!", - "content": "The awesome image I took while backpacking to modor", - "license": "creativecommons.org/licenses/by-sa/3.0/", - "id": "https://<server>/api/image/6_K9m-2NQFi37je845c83w", - "objectType": "image" - } - } - -.. warning:: Any other data submitted **will** be ignored. diff --git a/docs/source/api/media_interaction.rst b/docs/source/api/media_interaction.rst deleted file mode 100644 index 41114a71..00000000 --- a/docs/source/api/media_interaction.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - <http://creativecommons.org/publicdomain/zero/1.0/>. - -Pump.io supports a number of different interactions that can happen against -media. Theser are commenting, liking/favoriting and (re-)sharing. Currently -MediaGoblin supports just commenting although other interactions will come at -a later date. - --------------- -How to comment --------------- - -.. warning:: Commenting on a comment currently is NOT supported. - -Commenting is done by posting a comment activity to the users feed. The -activity should look similiar to:: - - { - "verb": "post", - "object": { - "objectType": "comment", - "inReplyTo": <media> - } - } - -This is where `<media>` is the media object you have got with from the server. - ----------------- -Getting comments ----------------- - -The media object you get back should have a `replies` section. This should -be an object which contains the number of replies and if there are any (i.e. -number of replies > 0) then `items` will include an array of every item:: - - { - "totalItems": 2, - "items: [ - { - "id": 1, - "objectType": "comment", - "content": "I'm a comment ^_^", - "author": <author user object> - }, - { - "id": 4, - "objectType": "comment", - "content": "Another comment! Blimey!", - "author": <author user object> - } - ], - "url": "http://some.server/api/images/1/comments/" - } - - diff --git a/docs/source/api/oauth.rst b/docs/source/api/oauth.rst deleted file mode 100644 index 003ad492..00000000 --- a/docs/source/api/oauth.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - <http://creativecommons.org/publicdomain/zero/1.0/>. - -============== -Authentication -============== - -GNU MediaGoblin uses OAuth1 to authenticate requests to the API. There are many -libraries out there for OAuth1, you're likely not going to have to do much. There -is a library for the GNU MediaGoblin called `PyPump <https://github.com/xray7224/PyPump>`_. -We are not using OAuth2 as we want to stay completely compatable with GNU MediaGoblin. - - -We use :doc:`client_register` to get the client ID and secret. - -Endpoints ---------- - -These are the endpoints you need to use for the oauth requests: - -`/oauth/request_token` is for getting the request token. - -`/oauth/authorize` is to send the user to to authorize your application. - -`/oauth/access_token` is for getting the access token to use in requests. - diff --git a/docs/source/api/objects.rst b/docs/source/api/objects.rst new file mode 100644 index 00000000..4c199616 --- /dev/null +++ b/docs/source/api/objects.rst @@ -0,0 +1,229 @@ +.. MediaGoblin Documentation + + Written in 2015 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + <http://creativecommons.org/publicdomain/zero/1.0/>. + +.. info:: Currently only image uploading is supported. + +======= +Objects +======= + +Using any the APIs mentioned in this document you will required +:doc:`authentication`. There are many ways to interact with objects, some of +which aren't supported yet by mediagoblin such as liking or sharing objects +however you can interact with them by updating them, deleting them and +commenting on them. + +Posting Objects +--------------- + +For the most part you should be able to post objects by creating the JSON +representation of the object on an activity and posting that to the user's +feed (outbox). Images however are slightly different and there are more steps +to it as you might imagine. + +Using posting a comment as an example, I'll show you how to post the object +to GNU MediaGoblin or pump.io. I first need to create the JSON representation +of the activity with the object but without the ID, URL, published or updated +timestamps or any other data the server creates. My activity comment is:: + + { + "verb": "post", + "object": { + "objectType": "comment", + "content": "This is my comment to be posted", + "inReplyTo": { + "id": "https://<server>/api/image/1" + } + } + } + +This should be posted to the users feed (outbox) which you can find out about +:doc:`activities`. You will get back the full activity containing all of +attributes including ID, urls, etc. + +Posting Media +~~~~~~~~~~~~~ + +Posting media is a special case from posting all other objects. This is because +you need to submit more than just the JSON image representation, you need to +actually subject the image itself. There is also strange behavour around media +postings where if you want to give the media you're posting a title or +description you need to peform an update too. A full media posting in order of +steps to do is as follows: + +1) Uploads the data to the server +2) Post media to feed +3) Update media to have title, description, license, etc. (optional) + +This could be condensed into a 2-step process however this would need to happen +upstream. If you would like to contribute to changing this upstream there is +an issue open: https://github.com/e14n/pump.io/issues/657 + +To upload media you should use the URL `/api/user/<username>/uploads`. + +A POST request should be made to the media upload URL submitting at least two +headers: + +* `Content-Type` - This being a valid mimetype for the media. +* `Content-Length` - size in bytes of the media. + +The media data should be submitted as POST data to the image upload URL. +You will get back a JSON encoded response which will look similar to:: + + { + "updated": "2014-01-11T09:45:48Z", + "links": { + "self": { + "href": "https://<server>/image/4wiBUV1HT8GRqseyvX8m-w" + } + }, + "fullImage": { + "url": "https://<server>//uploads/<username>/2014/1/11/V3cBMw.jpg", + "width": 505, + "height": 600 + }, + "replies": { + "url": "https://<server>//api/image/4wiBUV1HT8GRqseyvX8m-w/replies" + }, + "image": { + "url": "https://<server>/uploads/<username>/2014/1/11/V3cBMw_thumb.jpg", + "width": 269, + "height": 320 + }, + "author": { + "preferredUsername": "<username>", + "displayName": "<username>", + "links": { + "activity-outbox": { + "href": "https://<server>/api/user/<username>/feed" + }, + "self": { + "href": "https://<server>/api/user/<username>/profile" + }, + "activity-inbox": { + "href": "https://<server>/api/user/<username>/inbox" + } + }, + "url": "https://<server>/<username>", + "updated": "2013-08-14T10:01:21Z", + "id": "acct:<username>@<server>", + "objectType": "person" + }, + "url": "https://<server>/<username>/image/4wiBUV1HT8GRqseyvX8m-w", + "published": "2014-01-11T09:45:48Z", + "id": "https://<server>/api/image/4wiBUV1HT8GRqseyvX8m-w", + "objectType": "image" + } + +The main things in this response is `fullImage` which contains `url` (the URL +of the original image - i.e. fullsize) and `image` which contains `url` (the URL +of a thumbnail version). + +.. warning:: Media which have been uploaded but not submitted to a feed will + periodically be deleted. + +Once you've got the image object back you will need to submit the post +activity to the feed. This is exactly the same process as posting any other +object described above. You create a post activity and post that to the feed +(outbox) endpoint. The post activity looks like:: + + { + "verb": "post", + "object": { + "id": "https://<server>/api/image/4wiBUV1HT8GRqseyvX8m-w", + "objectType": "image" + } + } + +You will get back the full activity, unlike above however if you wish to +submit `displayName` (title) or `content` (description) information you need +to create an update activity and post that to the feed after you have posted +the image. An update activity would look like:: + + { + "verb": "update", + "object": { + "id": "https://<server>/api/image/4wiBUV1HT8GRqseyvX8m-w", + "displayName": "This is my title", + "content": "This is my description", + "objectType": "image" + } + } + +Updating Objects +---------------- + +If you would like to edit or update an object you can do so by submitting an +update activity. An update to a comment might look like:: + + { + "verb": "update", + "object": { + "id": "https://<server>/api/comment/1", + "objectType": "comment", + "content": "This is my new updated comment!" + } + } + +This should be posted to the feed (outbox). You will get back the full update +activity in response. + +Deleting Objects +---------------- + +Objects can be deleted by submitting a delete activity to the feed. A delete +object for a comment looks like:: + + { + "verb": "delete", + "object": { + "id": "https://<server>/api/comment/id", + "objectType": "comment" + } + } + +You should get the full delete activity in response. + +.. warning:: + While deletion works, currently because of the way deletion is implemented + deletion either via the API or the webUI causes any activities to be broken + and will be skipped and unaccessible. A migration to remove the broken + activities will come in a future release when soft-deletion has been + implemented. + +Posting Comments +---------------- + +Comments currently can only be on media objects, this however will change in +future versions of MediaGoblin to be inline with pump.io and Activity Streams +1.0 which allow comments to be on any object including comments themselves. + +If you want to submit a comment on an object it's very easy, it's just like +posting any other object except you use the `inReplyTo` attribute which +specifies the object you are commenting on. The `inReplyTo` needs to contain +the object or specifically the ID of it. + +Example of comment on an image:: + + { + "verb": "post", + "object": { + "content": "My comment here", + "inReplyTo": { + "id": "https://<server>/api/image/72" + } + } + } + +This should be posted to a feed and you will get back the full activity object +as with any other object posting. diff --git a/docs/source/conf.py b/docs/source/conf.py index 0b2bccac..0f53e4cf 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -219,7 +219,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', + ('index', 'mediagoblin', u'GNU MediaGoblin Documentation', [u'Chris Webber, et al'], 1) ] @@ -233,7 +233,7 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', u'gnumediagoblin', + ('index', 'mediagoblin', u'GNU MediaGoblin Documentation', u'mediagoblin', 'GNU MediaGoblin', 'Media sharing web application.', 'Miscellaneous'), ] diff --git a/docs/source/index.rst b/docs/source/index.rst index 8e49d1d1..a4fd2455 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -105,15 +105,14 @@ This chapter covers MediaGoblin's `Pump API work in progress; full federation is not supported at the moment, but media uploading works! You can use something like `PyPump <http://pypump.org>`_ -to write MediaGoblin uploadable applications.) +to write MediaGoblin applications.) .. toctree:: :maxdepth: 1 - api/client_register - api/oauth - api/media - api/media_interaction + api/authentication + api/activities + api/objects diff --git a/docs/source/plugindocs/oauth.rst b/docs/source/plugindocs/oauth.rst deleted file mode 100644 index 0685c9d1..00000000 --- a/docs/source/plugindocs/oauth.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../mediagoblin/plugins/oauth/README.rst diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 29adb691..a220eac1 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -42,7 +42,7 @@ exist yet: what to do then? The plan at present is that we are adding hooks as people need them, with community discussion. If you find that you need a hook and MediaGoblin at present doesn't provide it at present, please -`http://mediagoblin.org/pages/join.html <talk to us>`_! We'll +`talk to us <http://mediagoblin.org/pages/join.html>`_! We'll evaluate what to do from there. diff --git a/docs/source/siteadmin/configuration.rst b/docs/source/siteadmin/configuration.rst index 3da5cdd9..dd0d6cd9 100644 --- a/docs/source/siteadmin/configuration.rst +++ b/docs/source/siteadmin/configuration.rst @@ -109,6 +109,34 @@ they sound like. - email_smtp_user - email_smtp_pass +Changing data directory +----------------------- + +MediaGoblin by default stores your data in wherever ``data_basedir``. +This can be changed by changing the value in your ``mediagoblin.ini`` file +for example:: + + [DEFAULT] + data_basedir = "/var/mediagoblin/user_data" + +For efficiency reasons MediaGoblin doesn't serve these files itself and +instead leaves that to the webserver. You will have to alter the location +to match the path in ``data_basedir``. + +If you use ``lazyserver.sh`` you need to change the ``paste.ini`` file:: + + [app:mediagoblin] + /mgoblin_media = /var/mediagoblin/user_data + +If you use nginx you need to change the config:: + + # Instance specific media: + location /mgoblin_media/ { + alias /var/mediagoblin/user_data; + } + +Once you have done this you will need to move any existing media you had in the +old directory to the new directory so existing media still can be displayed. All other configuration changes ------------------------------- diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index dad489c5..e4042617 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -45,25 +45,26 @@ Dependencies MediaGoblin has the following core dependencies: -- Python 2.6 or 2.7 +- Python 2.7 - `python-lxml <http://lxml.de/>`_ - `git <http://git-scm.com/>`_ - `SQLite <http://www.sqlite.org/>`_/`PostgreSQL <http://www.postgresql.org/>`_ - `Python Imaging Library <http://www.pythonware.com/products/pil/>`_ (PIL) - `virtualenv <http://www.virtualenv.org/>`_ +- `nodejs <https://nodejs.org>`_ On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and derivatives) issue the following command:: - sudo apt-get install git-core python python-dev python-lxml \ - python-imaging python-virtualenv + # apt-get install git-core python python-dev python-lxml \ + python-imaging python-virtualenv npm automake On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the following command:: - yum install python-paste-deploy python-paste-script \ + # yum install python-paste-deploy python-paste-script \ git-core python python-devel python-lxml python-imaging \ - python-virtualenv + python-virtualenv npm automake Configure PostgreSQL ~~~~~~~~~~~~~~~~~~~~ @@ -79,27 +80,54 @@ Configure PostgreSQL These are the packages needed for Debian Wheezy (stable):: - sudo apt-get install postgresql postgresql-client python-psycopg2 + # apt-get install postgresql postgresql-client python-psycopg2 + +These are the packages needed for an RPM-based system:: + + # yum install postgresql postgresql-server python-psycopg2 + +An RPM-based system also requires that you initialize the PostgresSQL database +with this command. The following command is not needed on a Debian-based +platform, however:: + + # /usr/bin/postgresql-setup initdb The installation process will create a new *system* user named ``postgres``, -it will have privilegies sufficient to manage the database. We will create a +which will have privilegies sufficient to manage the database. We will create a new database user with restricted privilegies and a new database owned by our restricted database user for our MediaGoblin instance. In this example, the database user will be ``mediagoblin`` and the database name will be ``mediagoblin`` too. -To create our new user, run:: +We'll add these entities by first switching to the *postgres* account:: + + # su - postgres - sudo -u postgres createuser -A -D mediagoblin +This will change your prompt to a shell prompt, such as *-bash-4.2$*. Enter +the following *createuser* and *createdb* commands at that prompt. We'll +create the *mediagoblin* database user first:: -then create the database all our MediaGoblin data should be stored in:: + $ createuser -A -D mediagoblin - sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin +Then we'll create the database where all of our MediaGoblin data will be stored:: + + $ createdb -E UNICODE -O mediagoblin mediagoblin where the first ``mediagoblin`` is the database owner and the second ``mediagoblin`` is the database name. +Type ``exit`` to return to the *root* user prompt. From here we just need to +set the Postgres database to start on boot, and also start it up for this +particular session. If you're on a platform that does not use *systemd*, you +can enter:: + + # chkconfig postgresql on && service postgresql start + +Whereas users of *systemd*-based systems will need to enter:: + + # systemctl enable postgresql && systemctl start postgresql + .. caution:: Where is the password? These steps enable you to authenticate to the database in a password-less @@ -125,14 +153,10 @@ The following command (entered as root or with sudo) will create a system account with a username of ``mediagoblin``. You may choose a different username if you wish.:: - adduser --system mediagoblin + # useradd --system --user-group mediagoblin No password will be assigned to this account, and you will not be able -to log in as this user. To switch to this account, enter either:: - - sudo -u mediagoblin /bin/bash # (if you have sudo permissions) - -or:: +to log in as this user. To switch to this account, enter:: su mediagoblin -s /bin/bash # (if you have to use root permissions) @@ -143,11 +167,6 @@ You may get a warning similar to this when entering these commands:: You can disregard this warning. To return to your regular user account after using the system account, just enter ``exit``. -.. note:: - - Unless otherwise noted, the remainder of this document assumes that all - operations are performed using this unpriviledged account. - .. _create-mediagoblin-directory: Create a MediaGoblin Directory @@ -165,37 +184,35 @@ to the unpriviledged system account. To do this, enter either of the following commands, changing the defaults to suit your particular requirements:: - sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin: /srv/mediagoblin.example.org + # mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin: /srv/mediagoblin.example.org -or (as the root user):: +.. note:: - mkdir -p /srv/mediagoblin.example.org && chown -hR mediagoblin: /srv/mediagoblin.example.org + Unless otherwise noted, the remainder of this document assumes that all + operations are performed using this unpriviledged account. Install MediaGoblin and Virtualenv ---------------------------------- -.. note:: - - MediaGoblin is still developing rapidly. As a result - the following instructions recommend installing from the ``master`` - branch of the git repository. Eventually production deployments will - want to transition to running from more consistent releases. - We will now clone the MediaGoblin source code repository and setup and configure the necessary services. Modify these commands to -suit your own environment. As a reminder, you should enter these -commands using your unpriviledged system account. +suit your own environment. + +.. note:: + + As a reminder, you should enter these commands using your unpriviledged + *mediagoblin* system account. Change to the MediaGoblin directory that you just created:: - cd /srv/mediagoblin.example.org + $ cd /srv/mediagoblin.example.org Clone the MediaGoblin repository and set up the git submodules:: - git clone git://git.savannah.gnu.org/mediagoblin.git -b stable - cd mediagoblin - git submodule init && git submodule update + $ git clone git://git.savannah.gnu.org/mediagoblin.git -b stable + $ cd mediagoblin + $ git submodule init && git submodule update .. note:: @@ -205,21 +222,9 @@ Clone the MediaGoblin repository and set up the git submodules:: git remote set-url origin git://git.savannah.gnu.org/mediagoblin.git -And set up the in-package virtualenv:: - - (virtualenv --python=python2 --system-site-packages . || virtualenv --python=python2 .) && ./bin/python setup.py develop - -.. note:: - - We presently have an **experimental** make-style deployment system. if - you'd like to try it, instead of the above command, you can run:: +Set up the hacking environment:: - ./experimental-bootstrap.sh && ./configure && make - - This also includes a number of nice features, such as keeping your - viratualenv up to date by simply running `make update`. - - Note: this is liable to break. Use this method with caution. + $ ./bootstrap.sh && ./configure && make The above provides an in-package install of ``virtualenv``. While this is counter to the conventional ``virtualenv`` configuration, it is @@ -230,23 +235,20 @@ your preferred method. Assuming you are going to deploy with FastCGI, you should also install flup:: - ./bin/easy_install flup - -(Sometimes this breaks because flup's site is flakey. If it does for -you, try):: - - ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405 + $ ./bin/easy_install flup This concludes the initial configuration of the development environment. In the future, when you update your codebase, you should also run:: - git submodule update && ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate + $ git submodule update && ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate + +.. note:: -Note: If you are running an active site, depending on your server -configuration, you may need to stop it first or the dbupdate command -may hang (and it's certainly a good idea to restart it after the -update) + Note: If you are running an active site, depending on your server + configuration, you may need to stop it first or the dbupdate command + may hang (and it's certainly a good idea to restart it after the + update) Deploy MediaGoblin Services @@ -391,6 +393,18 @@ this ``nginx.conf`` file should be modeled on the following:: } } +The first four ``location`` directives instruct Nginx to serve the +static and uploaded files directly rather than through the MediaGoblin +process. This approach is faster and requires less memory. + +.. note:: + + The user who owns the Nginx process, normally ``www-data``, + requires execute permission on the directories ``static``, + ``public``, ``theme_static`` and ``plugin_static`` plus all their + parent directories. This user also requires read permission on all + the files within these directories. This is normally the default. + Now, nginx instance is configured to serve the MediaGoblin application. Perform a quick test to ensure that this configuration works. Restart nginx so it picks up your changes, with a command that @@ -436,3 +450,7 @@ Security Considerations and restart the server, so that it creates a new secret key. All previous sessions will be invalidated. +.. + Local variables: + fill-column: 70 + End: diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index f8030081..7d9f72b0 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -79,12 +79,15 @@ good/bad/ugly). On Debianoid systems .. code-block:: bash - sudo apt-get install python-gst0.10 \ - gstreamer0.10-plugins-base \ - gstreamer0.10-plugins-bad \ - gstreamer0.10-plugins-good \ - gstreamer0.10-plugins-ugly \ - gstreamer0.10-ffmpeg + sudo apt-get install python-gi python3-gi \ + gstreamer1.0-tools \ + gir1.2-gstreamer-1.0 \ + gir1.2-gst-plugins-base-1.0 \ + gstreamer1.0-plugins-good \ + gstreamer1.0-plugins-ugly \ + gstreamer1.0-plugins-bad \ + gstreamer1.0-libav \ + python-gst-1.0 Add ``[[mediagoblin.media_types.video]]`` under the ``[plugins]`` section in @@ -206,7 +209,7 @@ It may work on some earlier versions, but that is not guaranteed (and is surely not to work prior to Blender 2.5X). Add ``[[mediagoblin.media_types.stl]]`` under the ``[plugins]`` section in your -``mediagoblin_local.ini`` and restart MediaGoblin. +``mediagoblin_local.ini`` and restart MediaGoblin. Run @@ -255,7 +258,7 @@ This feature has been tested on Fedora with: It may work on some earlier versions, but that is not guaranteed. Add ``[[mediagoblin.media_types.pdf]]`` under the ``[plugins]`` section in your -``mediagoblin_local.ini`` and restart MediaGoblin. +``mediagoblin_local.ini`` and restart MediaGoblin. Run diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 11ee019f..101d9447 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -23,6 +23,15 @@ carefully, or at least skim over it. .. note:: + ALWAYS do backups before upgrading, especially before + running migrations! That way if something goes wrong, we can fix + things! + + And be sure to shut down your current mediagoblin/celery processes + before upgrading! + +.. note:: + The MediaGoblin repository used to be on gitorious.org, but since gitorious.org shut down, we had to move. We are presently on Savannah. You may need to update your git repository location:: @@ -78,7 +87,7 @@ That's it, probably! If you run into problems, don't hesitate to - Removed a false download link from setup.py 0.7.0 -==== +===== **Do this to upgrade** |