yetangitu/photo-documentation
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Initial checkin of docs

Browse source
This commit is contained in:
Jaisen Mathai 2013-01-28 22:49:14 -05:00
commit f22ce1ca1d
61 changed files with 5061 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

5
docs/Readme.markdown Normal file
View file

@ -0,0 +1,5 @@
OpenPhoto / Documentation
=======================
You can find the documentation at http://theopenphotoproject.org/documentation. It's a mirror of what is here but easier to follow.

27
docs/api/Authentication.markdown Normal file
View file

@ -0,0 +1,27 @@
Authentication using OAuth 1.0a
=======================
### Using OAuth (1.0a)
A full introduction to OAuth is beyond the scope of the OpenPhoto documentation.
In all reality you probably don't need to understand the ins and outs of OAuth, just grab one of our libraries.
* <a href="https://github.com/photo/openphoto-php">openphoto/openphoto-php</a> - Our PHP language binding.
* <a href="https://github.com/photo/openphoto-ruby">openphoto/openphoto-ruby</a> - Our Ruby language binding.
* <a href="https://github.com/photo/openphoto-python">openphoto/openphoto-python</a> - Our Python language binding.
* <a href="https://github.com/photo/openphoto-java">openphoto/openphoto-java</a> - Our Java language binding.
* More coming soon, <a href="mailto:hello@openphoto.me">contact us</a> if you'd like to write bindings in an unlisted language.
### Obtaining a consumer key and secret
Since OpenPhoto is distributed the flow to obtain a consumer key and secret differs slightly from typical OAuth applications.
Typically you would sign up for an application ID and be given a key and secret to be used with your app.
OpenPhoto differs because the host you'll be sending requests to is arbitrary and there's no central application repository.
### Resources on the web
If you're interested in learning more about OAuth then the following links are a great place to start.
* http://oauth.net/documentation/getting-started/
* http://hueniverse.com/oauth/guide/intro/
* http://www.slideshare.net/eran/introduction-to-oauth-presentation

41
docs/api/Envelope.markdown Normal file
View file

@ -0,0 +1,41 @@
Response Envelope
=======================
----------------------------------------
### Standard OpenPhoto API response envelope
Every API returns a JSON response adhering to the following format.
{
message: (string),
code: (int),
result: (mixed)
}
#### Message
The _message_ is a string which describes the action taken.
It's purely for informational purposes and should never be used in your code or relied on.
#### Code
The _code_ is an integer representing the status of the API call.
Typically the _code_ value should be _200_ but anything between _200_ and _299_ indicates a successful response.
The photo upload API, for example, will return a _202_ response indicating that the resource has been created.
Below are some common codes:
* _200_, The API call was successful
* _202_, Resource was created successfully
* _403_, Authentication failed when trying to complete the API call
* _404_, The requested endpoint could not be found
* _500_, An unknown error occured and hopefully the message has more information
#### Result
The _result_ can be any simple or complex value.
Consult the documentation for the endpoint you're using for information on what the _result_ will be.
The purpose of the _result_ is to allow you to continue processing the request.
We'll try to return the information you'll most likely need and aim to keep you from having to make a subsequent call to get it.

173
docs/api/GetActivities.markdown Normal file
View file

@ -0,0 +1,173 @@
Get Activities
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the Get Activities API
Use this API to get a user's activity feed.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: optional_
GET /activities/list.json
<a name="parameters"></a>
### Parameters
1. groupBy (optional), Time period to group activities by
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -h current.openphoto.me -e /activities/list.json
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->get("/tags/activities.json");
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, An array of activities
<a name="sample"></a>
#### Sample without `groupBy`
{
"message" : "User's list of activities",
"code" : 200,
"result" : [
{ // Photo object
"id" : "l", // activity id, not photo id. See photo object for photo id
"owner" : "jaisen+test@jmathai.com",
"appId" : "openphoto-frontend",
"type" : "photo-upload",
"data" : {
// Photo object
}
},
{ // comment
"id" : "p", // activity id, not photo id. See photo object for photo id
"owner" : "jaisen+test@jmathai.com",
"appId" : "openphoto-frontend",
"type" : "action-create",
"data" : {
"targetType" : "photo",
"target" : {
// Photo object
},
"action" : {
// Action object
}
},
"permission" : "1",
"dateCreated" : "1328851975"
}
]
}
#### Sample with `groupBy`
{
"message" : "User's list of activities",
"code" : 200,
"result" : {
"2012020921-photo-upload" : [ // photo uploads
{
"id" : "l", // activity id, not photo id. See photo object for photo id
"type" : "photo-upload",
"data" : {
// Photo object
},
"permission" : "1",
"dateCreated" : "1328851361"
},
{
"id" : "m", // activity id, not photo id. See photo object for photo id
"type" : "photo-upload",
"data" : {
// Photo object
},
"permission" : "1",
"dateCreated" : "1328851363"
}
],
"2012020921-action-create" : [
{
"id" : "p", // activity id, not photo id. See photo object for photo id
"type" : "action-create",
"data" : {
"targetType" : "photo",
"target" : {
// Photo object
},
"action" : {
// Action object
}
},
"permission" : "1",
"dateCreated" : "1328851975"
},
{
"id" : "q", // activity id, not photo id. See photo object for photo id
"owner" : "jaisen+test@jmathai.com",
"appId" : "openphoto-frontend",
"type" : "action-create",
"data" : {
"targetType" : "photo",
"target" : {
// Photo object
},
"action" : {
// Action object
}
},
"permission" : "1",
"dateCreated" : "1328852131"
}
]
}
}
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

93
docs/api/GetGroup.markdown Normal file
View file

@ -0,0 +1,93 @@
Get Group
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the Get Group API
Use this API to get a user's group.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
GET /group/:id/view.json
<a name="parameters"></a>
### Parameters
_None_
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
source secrets.sh
./openphoto -p -h current.openphoto.me -e /group/d/view.json
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->get("/group/d/view.json");
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, A [Group][Group] object
<a name="sample"></a>
#### Sample
{
"message" : "Your group",
"code" : 200,
"result" : {
"id" : "d",
"Name" : "d",
"name" : "Rachel and Jaisen",
"members" : [
"rachel.mathai@yahoo.com",
"jaisen@jmathai.com"
],
"appId" : "openphoto-frontend"
}
}
[Group]: http://theopenphotoproject.org/documentation/schemas/Group
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

115
docs/api/GetGroups.markdown Normal file
View file

@ -0,0 +1,115 @@
Get Groups
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the Get Groups API
Use this API to get a list of the user's groups.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
GET /groups/list.json
<a name="parameters"></a>
### Parameters
_None_
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
source secrets.sh
./openphoto -p -h current.openphoto.me -e /groups/list.json
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->get("/groups/list.json");
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, An array of [Group][Group] objects
<a name="sample"></a>
#### Sample
{
"message" : "A list of your groups",
"code" : 200,
"result" : [
{
"id" : "e",
"Name" : "e",
"name" : "Everyone else",
"members" : [
"rachel.mathai@yahoo.com",
"jaisen@jmathai.com",
"joe@joe.com"
],
"appId" : "openphoto-frontend"
},
{
"id" : "d",
"Name" : "d",
"name" : "Rachel and Jaisen",
"members" : [
"rachel.mathai@yahoo.com",
"jaisen@jmathai.com"
],
"appId" : "openphoto-frontend"
},
{
"id" : "f",
"Name" : "f",
"name" : "Random",
"members" : [
"joe@joe.com"
],
"appId" : "openphoto-frontend"
}
]
}
[Group]: http://theopenphotoproject.org/documentation/schemas/Group
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

94
docs/api/GetHelloWorld.markdown Normal file
View file

@ -0,0 +1,94 @@
Hello World
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the Get Hello World API
This endpoint is used to test connectivity and/or authentication. Any parameters passed in the query string are returned in the response.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: optional_
GET /hello.json
<a name="parameters"></a>
### Parameters
1. auth (optional), Pass this in with a value of `true` to test OAuth requests.
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
# without authentication
./openphoto -p -h current.openphoto.me -e /hello.json
# with authentication
./openphoto -p -h current.openphoto.me -e /hello.json -F 'auth=true'
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
// without authentication
$client = new OpenPhotoOAuth($host);
$response = $client->get("/hello.json");
// with authentication
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->get("/hello.json", array('auth' => 'true'));
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, Any GET parameters passed in to the request plus `__route__`.
<a name="sample"></a>
#### Sample
{
"message":"Hello, world!",
"code":200,
"result":
{
"__route__":"\/hello.json"
}
}
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

116
docs/api/GetPhoto.markdown Normal file
View file

@ -0,0 +1,116 @@
Get Photo
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the Get Photo API
Use this API to get a for a user's photo.
_NOTE:_ Always pass in the `returnSizes` parameter for sizes you plan on using. It's the only way to guarantee that a URL for that size will be present in the response. See [Photo Generation](http://theopenphotoproject.org/documentation/faq/PhotoGeneration) for details.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: optional_
GET /photo/:id/view.json
<a name="parameters"></a>
### Parameters
1. returnSizes (optional), (i.e. 20x20 or 30x30xCR,40x40) The photo sizes you'd like in the response. Specify every size you plan on using. [Docs for this parameter](http://theopenphotoproject.org/documentation/faq/ReturnSizes)
1. generate (optional), (i.e. true or false) Tells the API to generate the sizes from `returnSizes` instead of returning a _create_ URL. [Docs for this parameter](http://theopenphotoproject.org/documentation/faq/ReturnSizes)
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -h current.openphoto.me -e /photo/b/view.json
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->get("/photo/b/view.json");
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, A [Photo][Photo] object
<a name="sample"></a>
#### Sample
{
"message":"",
"code":200,
"result":{
"id":"hl"
"tags":[
""
],
"pathBase":"\/base\/201107\/1311045184-opme7Z0WBh.jpg",
"appId":"opme",
"host":"testjmathai1.s3.amazonaws.com",
"dateUploadedMonth":"07",
"status":"1",
"hash":"fba49a238426ac3485af6d69967ccd2d08c1fe5c",
"width":"569",
"dateTakenMonth":"07",
"dateTakenDay":"18",
"permission":"0",
"pathOriginal":"\/original\/201107\/1311045184-opme7Z0WBh.jpg",
"exifCameraMake":"",
"size":"0",
"dateTaken":"1311045184",
"height":"476",
"views":"0",
"dateUploadedYear":"2011",
"dateTakenYear":"2011",
"creativeCommons":"BY-NC",
"dateUploadedDay":"18",
"dateUploaded":"1311045188",
"exifCameraModel":"",
"path200x200":"\/custom\/201107\/1311045184-opme7Z0WBh_200x200.jpg",
}
}
[Photo]: http://theopenphotoproject.org/documentation/schemas/Photo
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[photogeneration]: http://theopenphotoproject.org/documentation/faq/PhotoGeneration
[ReturnSizes]: http://theopenphotoproject.org/documentation/faq/ReturnSizes
[openphoto-php]: https://github.com/photo/openphoto-php

159
docs/api/GetPhotoNextPrevious.markdown Normal file
View file

@ -0,0 +1,159 @@
Get Next/Previous Photo
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the Get Photo API
Use this API to get the next and previous photo given a photo in the middle.
_NOTE:_ Always pass in the `returnSizes` parameter for sizes you plan on using. It's the only way to guarantee that a URL for that size will be present in the response. See [Photo Generation](http://theopenphotoproject.org/documentation/faq/PhotoGeneration) for details.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: optional_
GET /photo/:id/nextprevious.json
<a name="parameters"></a>
### Parameters
1. returnSizes (optional), (i.e. 20x20 or 30x30xCR,40x40) The photo sizes you'd like in the response. Specify every size you plan on using. [Docs for this parameter](http://theopenphotoproject.org/documentation/faq/ReturnSizes)
1. generate (optional), (i.e. true or false) Tells the API to generate the sizes from `returnSizes` instead of returning a _create_ URL. [Docs for this parameter](http://theopenphotoproject.org/documentation/faq/ReturnSizes)
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -h current.openphoto.me -e /photo/b/nextprevious.json
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->get("/photo/b/nextprevious.json");
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, An array of [Photo][Photo] objects
<a name="sample"></a>
#### Sample
{
"message" : "Next\/previous for photo bq",
"code" : 200,
"result" : {
"previous" : {
"tags" : [
],
"id" : "bo",
"appId" : "openphoto-frontend",
"pathBase" : "\/base\/201109\/1317155744-DSC_9243.JPG",
"dateUploadedMonth" : "09",
"dateTakenMonth" : "08",
"exifCameraMake" : "NIKON CORPORATION",
"dateTaken" : "1313454314",
"title" : "",
"height" : "2000",
"description" : "",
"dateTakenYear" : "2011",
"longitude" : "",
"dateUploadedDay" : "27",
"host" : "opmecurrent.s3.amazonaws.com",
"hash" : "7b923cbbe4f7aa81be144b1420a99711ad57106b",
"status" : "1",
"width" : "3008",
"dateTakenDay" : "15",
"permission" : "1",
"pathOriginal" : "\/original\/201109\/1317155744-DSC_9243.JPG",
"size" : "2502",
"dateUploadedYear" : "2011",
"views" : "0",
"latitude" : "",
"dateUploaded" : "1317155745",
"exifCameraModel" : "NIKON D70s",
"Name" : "bo",
"exifFocalLength" : "35",
"exifExposureTime" : "10\/600",
"exifISOSpeed" : "",
"license" : "",
"exifFNumber" : "3.8"
},
"next" : {
"tags" : [
],
"id" : "63",
"appId" : "current.openphoto.me",
"pathBase" : "\/base\/201108\/1313010849-opmeTbrBki.jpg",
"dateUploadedMonth" : "08",
"dateTakenMonth" : "08",
"exifCameraMake" : "",
"dateTaken" : "1313010850",
"title" : "Gulf Shores, AL",
"height" : "1936",
"description" : "",
"creativeCommons" : "BY-NC",
"dateTakenYear" : "2011",
"dateUploadedDay" : "10",
"longitude" : "-87.7008193",
"host" : "opmecurrent.s3.amazonaws.com",
"hash" : "20d64642f09befc4004c22269e698e6e43475963",
"status" : "1",
"width" : "2592",
"dateTakenDay" : "10",
"permission" : "1",
"pathOriginal" : "\/original\/201108\/1313010849-opmeTbrBki.jpg",
"size" : "1513",
"dateUploadedYear" : "2011",
"views" : "0",
"latitude" : "30.2460361",
"dateUploaded" : "1313010853",
"exifCameraModel" : "",
"Name" : "63"
}
}
}
[Photo]: http://theopenphotoproject.org/documentation/schemas/Photo
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[photogeneration]: http://theopenphotoproject.org/documentation/faq/PhotoGeneration
[ReturnSizes]: http://theopenphotoproject.org/documentation/faq/ReturnSizes
[openphoto-php]: https://github.com/photo/openphoto-php

149
docs/api/GetPhotos.markdown Normal file
View file

@ -0,0 +1,149 @@
Get Photos
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the Get Photos API
Use this API to get a set of photos for a user.
_NOTE:_ Always pass in the `returnSizes` parameter for sizes you plan on using. It's the only way to guarantee that a URL for that size will be present in the response. See [Photo Generation](http://theopenphotoproject.org/documentation/faq/PhotoGeneration) for details.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: optional_
GET /photos.json
<a name="parameters"></a>
### Parameters
1. returnSizes (optional), (i.e. 20x20 or 30x30xCR,40x40) The photo sizes you'd like in the response. Specify every size you plan on using. [Docs for this parameter](http://theopenphotoproject.org/documentation/faq/ReturnSizes)
1. generate (optional), (i.e. true or false) Tells the API to generate the sizes from `returnSizes` instead of returning a _create_ URL. [Docs for this parameter](http://theopenphotoproject.org/documentation/faq/ReturnSizes)
1. pageSize (optional), Number of photos to return per request.
1. page (optional), Page number when browsing through photos. Starts at 1.
1. tags (optional), _i.e. dog,cat_ - A comma delimited string of strings.
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -h current.openphoto.me -e /photos/list.json -F 'tags=sunnyvale'
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->get("/photos/list.json", array('tags' => 'sunnyvale'));
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, An array of [Photo][Photo] objects
<a name="sample"></a>
#### Sample
{
"message":"",
"code":200,
"result":[
{
"tags":[
""
],
"pathBase":"\/base\/201107\/1311045184-opme7Z0WBh.jpg",
"appId":"opme",
"host":"testjmathai1.s3.amazonaws.com",
"dateUploadedMonth":"07",
"status":"1",
"hash":"fba49a238426ac3485af6d69967ccd2d08c1fe5c",
"width":"569",
"dateTakenMonth":"07",
"dateTakenDay":"18",
"permission":"0",
"pathOriginal":"\/original\/201107\/1311045184-opme7Z0WBh.jpg",
"exifCameraMake":"",
"size":"0",
"dateTaken":"1311045184",
"height":"476",
"views":"0",
"dateUploadedYear":"2011",
"dateTakenYear":"2011",
"creativeCommons":"BY-NC",
"dateUploadedDay":"18",
"dateUploaded":"1311045188",
"exifCameraModel":"",
"path200x200":"\/custom\/201107\/1311045184-opme7Z0WBh_200x200.jpg",
"id":"hl"
},
{
"tags":[
""
],
"pathBase":"\/base\/201107\/1311027064-opme0WBhqP.jpg",
"appId":"opme",
"host":"testjmathai1.s3.amazonaws.com",
"dateUploadedMonth":"07",
"status":"1",
"hash":"fba49a238426ac3485af6d69967ccd2d08c1fe5c",
"width":"569",
"dateTakenMonth":"07",
"dateTakenDay":"18",
"permission":"0",
"pathOriginal":"\/original\/201107\/1311027064-opme0WBhqP.jpg",
"exifCameraMake":"",
"size":"0",
"dateTaken":"1311027064",
"height":"476",
"views":"0",
"dateUploadedYear":"2011",
"dateTakenYear":"2011",
"creativeCommons":"BY-NC",
"dateUploadedDay":"18",
"dateUploaded":"1311027066",
"exifCameraModel":"",
"id":"ob"
}
]
}
[Photo]: http://theopenphotoproject.org/documentation/schemas/Photo
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[photogeneration]: http://theopenphotoproject.org/documentation/faq/PhotoGeneration
[ReturnSizes]: http://theopenphotoproject.org/documentation/faq/ReturnSizes
[openphoto-php]: https://github.com/photo/openphoto-php

107
docs/api/GetTags.markdown Normal file
View file

@ -0,0 +1,107 @@
Get Tags
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the Get Tags API
Use this API to get a user's tags.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: optional_
GET /tags/list.json
<a name="parameters"></a>
### Parameters
_None_
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -h current.openphoto.me -e /tags/list.json
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->get("/tags/list.json");
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, An array of [Tag][Tag] objects
<a name="sample"></a>
#### Sample
{
"message":"",
"code":200,
"result":
[
{
"id": "mountain",
"count": 1
},
{
"id": "jaisen",
"count": 10,
"email": "jaisen@jmathai.com"
},
{
"id": "New York",
"count": 9,
"latitude": 12.3456,
"longitude": 78.9012
},
{
"id": "Sunnyvale",
"count":23
"latitude": 13.579,
"longitude": 24.68
},
....
]
}
[Tag]: http://theopenphotoproject.org/documentation/schemas/Tag
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

92
docs/api/GetWebhook.markdown Normal file
View file

@ -0,0 +1,92 @@
Get Webhook
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the GET Webhook API
Use this API to get a user's Webhook.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
GET /webhook/:id/view.json
<a name="parameters"></a>
### Parameters
_None_
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
source secrets.sh
./openphoto -p -h current.openphoto.me -e /webhook/abcdefghijklmnopqrstuvwxyz/view.json
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->get("/webhook/abcdefghijklmnopqrstuvwxyz/view.json");
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, A [Webhook][Webhook] object
<a name="sample"></a>
#### Sample
{
"message" : "Your group",
"code" : 200,
"result" : {
id: "abcdefghijklmnopqrstuvwxyz",
appId: "current.openphoto.me",
callback: "http://somehost.com/somepath",
topic: "photo.upload",
verifyToken: "qazwsxedcrfvz",
challenge: "plmoknijbuhv",
secret: "rfvtgbyhn"
}
}
[Webhook]: http://theopenphotoproject.org/documentation/schemas/Webhook
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

1
docs/api/GetWebhooks.markdown Normal file
View file

@ -0,0 +1 @@
Not yet documented

100
docs/api/PostActionCreate.markdown Normal file
View file

@ -0,0 +1,100 @@
Create Action
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the create action API
Use this API to create an action on a photo. This includes comments and favorites.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /action/:targetId/photo/create.json
<a name="parameters"></a>
### Parameters
1. email (required), Email address of the user performing this action
1. name (optional), Name of the user performing this action
1. website (optional), URL of the user performing this action
1. targetUrl (optional), URL of the object this action is being performed on
1. permalink (optional), Permalink URL of this action
1. type (required), _i.e. comment or favorite_ - Type of action
1. value (required), Text representing the comment or favorite
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -X POST -h current.openphoto.me -e /action/photo/a/create.json -F 'type=comment' -F 'value=Here is my comment' -F 'email=jaisen@jmathai.com'
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->post("/action/photo/a/create.json", array('type' => 'comment', 'value' => 'Here is my comment', 'email' => 'jaisen@jmathai.com'));
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, A [Action][Action] object or FALSE on error
<a name="sample"></a>
#### Sample
{
"message":"",
"code":200,
"result":
{
id: "a",
appId: "current.openphoto.me",
targetId: "b",
targetType: "photo",
email: "jaisen@jmathai.com",
type: "comment",
value: "Here is my comment",
datePosted: "1318281477",
status: 1
}
}
[Action]: http://theopenphotoproject.org/documentation/schemas/Action
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

83
docs/api/PostActionDelete.markdown Normal file
View file

@ -0,0 +1,83 @@
Delete Action
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the delete action API
Use this API to delete an action on a photo. This includes comments and favorites.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /action/photo/:targetId/delete.json
<a name="parameters"></a>
### Parameters
_N/A_
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -X POST -h current.openphoto.me -e /action/photo/a/delete.json
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->post("/action/photo/a/delete.json");
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _204_ on success
* _result_, boolean
<a name="sample"></a>
#### Sample
{
"message":"",
"code":204,
"result": true
}
[Action]: http://theopenphotoproject.org/documentation/schemas/Action
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

90
docs/api/PostGroupCreate.markdown Normal file
View file

@ -0,0 +1,90 @@
Create Group
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the create Group API
Use this API to create a group.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /group/create.json
<a name="parameters"></a>
### Parameters
1. name (required), The name of the group to create
1. members (optional), _i.e. jaisen@jmathai.com,hello@openphoto.me_ - A comma delimited list of email addresses
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -X POST -h current.openphoto.me -e /group/create.json -F 'name=My Group' -F 'members=jaisen@jmathai.com'
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->post("/group/create.json", array('name' => 'My Group', 'members' => 'jaisen@jmathai.com'));
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, A [Group][Group] object or FALSE on error
<a name="sample"></a>
#### Sample
{
"message":"",
"code":200,
"result":
{
id: 'a',
appId: 'current.openphoto.me',
name: 'My Group',
members: ['jaisen@jmathai.com','hello@openphoto.me']
}
}
[Group]: http://theopenphotoproject.org/documentation/schemas/Group
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

83
docs/api/PostGroupDelete.markdown Normal file
View file

@ -0,0 +1,83 @@
Delete Group
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the delete Group API
Use this API to delete a group.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /group/:id/delete.json
<a name="parameters"></a>
### Parameters
_None_
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -X POST -h current.openphoto.me -e /group/a/delete.json
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->post("/group/a/delete.json");
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _204_ on success
* _result_, A boolean
<a name="sample"></a>
#### Sample
{
"message":"",
"code":204,
"result": true
}
[Group]: http://theopenphotoproject.org/documentation/schemas/Group
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

90
docs/api/PostGroupUpdate.markdown Normal file
View file

@ -0,0 +1,90 @@
Update Group
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the update Group API
Use this API to update a group.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /group/:id/update.json
<a name="parameters"></a>
### Parameters
1. name (optional), The name of the group to create
1. members (optional), _i.e. jaisen@jmathai.com,hello@openphoto.me_ - A comma delimited list of email addresses
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -X POST -h current.openphoto.me -e /group/a/update.json -F 'members=jaisen@jmathai.com'
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->post("/group/a/update.json", array('members' => 'jaisen@jmathai.com'));
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, A [Group][Group] object or FALSE on error
<a name="sample"></a>
#### Sample
{
"message":"",
"code":200,
"result":
{
id: 'a',
appId: 'current.openphoto.me',
name: 'My Group',
members: ['jaisen@jmathai.com']
}
}
[Group]: http://theopenphotoproject.org/documentation/schemas/Group
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

82
docs/api/PostPhotoDelete.markdown Normal file
View file

@ -0,0 +1,82 @@
Delete Photo
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the delete action API
Use this API to delete an action.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /action/:id/delete.json
<a name="parameters"></a>
### Parameters
_None_
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -X POST -h current.openphoto.me -e /action/a/delete.json
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->post("/action/a/delete.json");
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _204_ on success
* _result_, Boolean
<a name="sample"></a>
#### Sample
{
"message":"",
"code":204,
"result":true
}
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

125
docs/api/PostPhotoUpdate.markdown Normal file
View file

@ -0,0 +1,125 @@
Update Photo
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the Photo update API
This API is used to update an existing photo's metadata for a user.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /photo/:id/update.json
<a name="parameters"></a>
### Parameters
1. permission (optional), 0 for private and 1 for public.
1. title (optional), _i.e. My first day at work_ - A string title to describe the photo.
1. description (optional), _i.e. A much longer description of my first day_ - A string to describe the photo in detail.
1. tags (optional), _i.e. dog,cat_ - A comma delimited string of alpha numeric strings.
1. tagsAdd (optional), _i.e. dog,cat_ - A comma delimited string of alpha numeric strings to be added.
1. tagsRemove (optional), _i.e. dog,cat_ - A comma delimited string of alpha numeric strings to be removed.
1. dateUploaded (optional), _i.e. 1311059035_ - A unix timestamp of the date the photo was uploaded
1. dateTaken (optional), _i.e. 1311059035_ - A unix timestamp of the date the photo was taken which overrides EXIF data if present
1. license (optional), _i.e. CC BY-SA or My Custom License_ - A string representing a custom or Creative Commons license.
1. latitude (optional), _i.e. 34.76_ - A decimal representation of latitude.
1. longitude (optional), _i.e. -87.45_ - A decimal representation of longitude.
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
source secrets.sh
./openphoto -p -X POST -h current.openphoto.me -e /photo/a/update.json -F 'title=My Photo Title' -F 'tags=sunnyvale,downtown'
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->post("/photo/a/update.json", array('title' => 'My Photo Title', 'tags' => 'sunnyvale,downtown'));
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _202_ on success
* _result_, A [Photo][Photo] object or FALSE on error
<a name="sample"></a>
#### Sample
{
"message":"Photo 8i uploaded successfully",
"code":202,
"result":{
"id":"8i",
"tags":[
"dog",
"cat"
],
"pathBase":"\/base\/201107\/1311053366-huge.jpg",
"appId":"opme",
"host":"testjmathai1.s3.amazonaws.com",
"dateUploadedMonth":"07",
"status":"1",
"hash":"6d7a9b0af31073a76ff2e79ee44b5c4951671fa2",
"width":"4288",
"dateTakenMonth":"07",
"dateTakenDay":"03",
"permission":"0",
"pathOriginal":"\/original\/201107\/1311053366-huge.jpg",
"exifCameraMake":"NIKON CORPORATION",
"size":"5595",
"dateTaken":"1309707719",
"height":"2848",
"views":"0",
"dateUploadedYear":"2011",
"dateTakenYear":"2011",
"creativeCommons":"BY-NC",
"dateUploadedDay":"18",
"dateUploaded":"1311053403",
"exifCameraModel":"NIKON D90",
"longitude":"-89.24",
"latitude":"37.65",
"path300x300":"\/custom\/201107\/1311053366-huge_300x300.jpg",
}
}
[Photo]: http://theopenphotoproject.org/documentation/schemas/Photo
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

139
docs/api/PostPhotoUpload.markdown Normal file
View file

@ -0,0 +1,139 @@
Upload Photo
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the Photo Upload API
This API is used to upload a new photo for a user.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /photo/upload.json
<a name="parameters"></a>
### Parameters
(Due to a [bug in PHP's PECL OAuth extension](https://github.com/photo/frontend/issues/289) all parameters except for the photo must be passed urlencoded in the query string. This only applies for multipart and not application/x-www-form-urlencoded requests).
1. photo (required), The photo to be uploaded.
* This can be the binary photo in multipart/formdata
* This can be the base64 encoded value of the photo in application/x-www-form-urlencoded
1. permission (optional), 0 for private and 1 for public.
1. title (optional), _e.g. My first day at work_ - A string title to describe the photo.
1. description (optional), _e.g. A much longer description of my first day_ - A string to describe the photo in detail.
1. tags (optional), _e.g. dog,cat_ - A comma delimited string of alpha numeric strings.
1. dateUploaded (optional), _i.e. 1311059035_ - A unix timestamp of the date the photo was uploaded
1. dateTaken (optional), _e.g. 1311059035_ - A unix timestamp of the date the photo was taken which overrides EXIF data if present
1. license (optional), _e.g. CC BY-SA or My Custom License_ - A string representing a custom or Creative Commons license.
1. latitude (optional), _e.g. 34.76_ - A decimal representation of latitude.
1. longitude (optional), _e.g. -87.45_ - A decimal representation of longitude.
1. returnSizes (optional), _e.g. 200x200,300x300xBW_ - A string instructing specific versions of the photo to be autogenerated.
To specify multiple sizes then separate each with a comman.
The url will be present in the response.
* 300x300 - A photo which maintains aspect ratio and fits inside a 300x300 square
* 1024x768xCR - A photo that's exactly 1024x768 pixels cropped to the center in an optimized manner
* 160x90xBWxCR - A photo that's cropped exactly to 160x90 in greyscale (black and white)
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
source secrets.sh
./openphoto -p -X POST -h current.openphoto.me -e /photo/upload.json -F 'photo=@/path/to/photo.jpg' -F 'tags=sunnyvale,downtown'
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
// multipart
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->post("/photo/upload.json", array('photo' => '@/path/to/photo.jpg', 'tags' => 'sunnyvale,downtown'));
// base64 encoded
$photoBase64Encoded = base64_encode(file_get_contents('/path/to/photo.jpg'));
$response = $client->post("/photo/upload.json", array('photo' => $photoBase64Encoded, 'tags' => 'sunnyvale,downtown'));
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _202_ on success
* _result_, A [Photo][Photo] object
<a name="sample"></a>
#### Sample
{
"message":"Photo 8i uploaded successfully",
"code":202,
"result":{
"id":"8i",
"tags":[
"dog",
"cat"
],
"pathBase":"\/base\/201107\/1311053366-huge.jpg",
"appId":"opme",
"host":"testjmathai1.s3.amazonaws.com",
"dateUploadedMonth":"07",
"status":"1",
"hash":"6d7a9b0af31073a76ff2e79ee44b5c4951671fa2",
"width":"4288",
"dateTakenMonth":"07",
"dateTakenDay":"03",
"permission":"0",
"pathOriginal":"\/original\/201107\/1311053366-huge.jpg",
"exifCameraMake":"NIKON CORPORATION",
"size":"5595",
"dateTaken":"1309707719",
"height":"2848",
"views":"0",
"dateUploadedYear":"2011",
"dateTakenYear":"2011",
"creativeCommons":"BY-NC",
"dateUploadedDay":"18",
"dateUploaded":"1311053403",
"exifCameraModel":"NIKON D90",
"longitude":"-89.24",
"latitude":"37.65",
"path300x300":"\/custom\/201107\/1311053366-huge_300x300.jpg",
}
}
[Photo]: http://theopenphotoproject.org/documentation/schemas/Photo
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

92
docs/api/PostTagCreate.markdown Normal file
View file

@ -0,0 +1,92 @@
Create Tag
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the Create Tag API
Use this API to create a tag.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /tag/create.json
<a name="parameters"></a>
### Parameters
1. tag (required), The name of the tag to create
1. count (optional), Number of photos which contain this tag
1. email (optional), An email address that corresponds to this tag
1. latitude (optional), _i.e. 34.76_ - A decimal representation of latitude.
1. longitude (optional), _i.e. -87.45_ - A decimal representation of longitude.
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -X POST -h current.openphoto.me -e /tag/create.json -F 'tag=sunnyvale' -F 'count=10'
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->post("/tag/create.json", array('tag' => 'sunnyvale', 'count' => 10));
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _201_ on success
* _result_, A [Tag][Tag] object or FALSE on error
<a name="sample"></a>
#### Sample
{
"message":"",
"code":201,
"result":
{
"id": "mountain",
"count": 0
}
}
[Tag]: http://theopenphotoproject.org/documentation/schemas/Tag
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

91
docs/api/PostTagUpdate.markdown Normal file
View file

@ -0,0 +1,91 @@
Update Tag
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the update Tag API
Use this API to update a tag.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /tag/:id/update.json
<a name="parameters"></a>
### Parameters
1. count (optional), Number of photos which contain this tag
1. email (optional), An email address that corresponds to this tag
1. latitude (optional), _i.e. 34.76_ - A decimal representation of latitude.
1. longitude (optional), _i.e. -87.45_ - A decimal representation of longitude.
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
./openphoto -p -X POST -h current.openphoto.me -e /tag/sunnyvale/update.json -F 'count=10'
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->post("/tag/sunnyvale/update.json", array('count' => 10));
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _200_ on success
* _result_, A [Tag][Tag] object or FALSE on error
<a name="sample"></a>
#### Sample
{
"message":"",
"code":200,
"result":
{
"id": "mountain",
"count": 1
}
}
[Tag]: http://theopenphotoproject.org/documentation/schemas/Tag
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

86
docs/api/PostWebhookDelete.markdown Normal file
View file

@ -0,0 +1,86 @@
Delete Webhook
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
1. [Examples][examples]
* [Command line][example-cli]
* [PHP][example-php]
1. [Response][response]
* [Sample][sample]
----------------------------------------
<a name="purpose"></a>
### Purpose of the POST Webhook delete API
Use this API to delete an existing webhook for a user.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /webhook/:id/delete.json
<a name="parameters"></a>
### Parameters
_None_
----------------------------------------
<a name="examples"></a>
### Examples
<a name="example-cli"></a>
#### Command Line (using [openphoto-php][openphoto-php])
source secrets.sh
./openphoto -p -X POST -h current.openphoto.me -e /webhook/abcdefghijklmnopqrstuvwxyz/delete.json
<a name="example-php"></a>
#### PHP (using [openphoto-php][openphoto-php])
$client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
$response = $client->post('/webhook/abcdefghijklmnopqrstuvwxyz/delete.json');
----------------------------------------
<a name="response"></a>
### Response
The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope).
* _message_, A string describing the result. Don't use this for anything but reading.
* _code_, _204_ on success
* _result_, A boolean
<a name="sample"></a>
#### Sample
{
"message" : "Webhook deleted successfully",
"code" : 204,
"result" : true
}
[Webhook]: http://theopenphotoproject.org/documentation/schemas/Webhook
[webhookverification]: http://theopenphotoproject.org/documentation/faq/WebhookVerification
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
[examples]: #examples
[example-cli]: #example-cli
[example-php]: #example-php
[response]: #response
[sample]: #sample
[openphoto-php]: https://github.com/photo/openphoto-php

49
docs/api/PostWebhookSubscribe.markdown Normal file
View file

@ -0,0 +1,49 @@
Create/Subscribe to Webhook
=======================
----------------------------------------
1. [Purpose][purpose]
1. [Endpoint][endpoint]
1. [Parameters][parameters]
----------------------------------------
<a name="purpose"></a>
### Purpose of the POST Webhook create API
Use this API to create a new webhook for a user.
This API differs from our others in that it's both interactive and does not return a [Standard Envelope](http://theopenphotoproject.org/documentation/api/Envelope). These are the steps required to complete a webhook subscription.
<a name="verification"></a>
1. The consumer _(you)_ makes a POST request to the provider _(the API host)_ to `http://apihost.com/webhook/subscribe` with the <a href="#">required parameters</a>.
1. The provider makes a GET request back to your `callback` URL passing along a `mode`, `topic`, and `challenge` parameter. A `verifyToken` parameter is passed back if originally supplied.
1. The consumer must validate that the subscription was intended (typically using the `verifyToken`) and print out the `challenge` value with a HTTP 200 response code.
1. If the consumer response is a HTTP 200 and the content body was equal to `challenge` then the provider completes the subscription.
----------------------------------------
<a name="endpoint"></a>
### Endpoint
_Authentication: required_
POST /webhook/subscribe
<a name="parameters"></a>
### Parameters
1. callback (required), A URL to POST to. This also needs to handle GET calls for the <a href="#verification">verification process</a>.
1. topic (required), _i.e. photo.upload_ - The topic which you'd like to subscribe to.
1. mode (required), Only _sync_ is supported at this time.
1. verifyToken (optional), A provider generated string to which is passed back as part of the <a href="#verification">verification process</a>.
----------------------------------------
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters

75
docs/api/Readme.markdown Normal file
View file

@ -0,0 +1,75 @@
Open Photo API
=======================
----------------------------------------
### How do I authenticate?
The Open Photo API uses [OAuth1.0a](http://oauth.net/core/1.0a/) for authentication. See the complete [guide on authentication](http://theopenphotoproject.org/documentation/api/Authentication) for details.
### What's the response format?
Every API endpoint returns a JSON response in a [standard envelope](http://theopenphotoproject.org/documentation/api/Envelope).
{
message: "A string describing the response",
code: 200,
result: {
foo: "bar"
}
}
### API Endpoints
#### Test / diagnostics endpoints
1. [GET /hello.json](http://theopenphotoproject.org/documentation/api/GetHelloWorld)
Test endpoint.
#### Action endpoings (comments, favorites, etc)
1. [POST /action/:id/:type/create.json](http://theopenphotoproject.org/documentation/api/PostActionCreate)
Create an action.
1. [POST /action/:id/delete.json](http://theopenphotoproject.org/documentation/api/PostActionDelete)
Delete an action.
#### Photo endpoints
1. [POST /photos/:id/delete.json](http://theopenphotoproject.org/documentation/api/PostPhotoDelete)
Delete a user's photo.
1. [POST /photos/:id/update.json](http://theopenphotoproject.org/documentation/api/PostPhotoUpdate)
Update data on a user's photo.
1. [GET /photo/:id/view.json](http://theopenphotoproject.org/documentation/api/GetPhoto)
Get a user's photo.
1. [GET /photos/list.json](http://theopenphotoproject.org/documentation/api/GetPhotos)
Get a list of the user's photos.
1. [GET /photo/:id/nextprevious.json](http://theopenphotoproject.org/documentation/api/GetPhotoNextPrevious)
Get the next and previous photo.
1. [POST /photo/upload.json](http://theopenphotoproject.org/documentation/api/PostPhotoUpload)
Upload a new photo.
#### Tag endpoints
1. [GET /tags/list.json](http://theopenphotoproject.org/documentation/api/GetTags)
Get a user's tags.
1. [POST /tag/create.json](http://theopenphotoproject.org/documentation/api/PostTagCreate)
Create a tag for the user.
1. [POST /tag/:id/update.json](http://theopenphotoproject.org/documentation/api/PostTagUpdate)
Modify meta data for a user's tag.
#### Group endpoints
1. [GET /group/:id/view.json](http://theopenphotoproject.org/documentation/api/GetGroup)
Get a group.
1. [GET /groups/list.json](http://theopenphotoproject.org/documentation/api/GetGroups)
Get a listing of a user's groups.
1. [POST /group/create.json](http://theopenphotoproject.org/documentation/api/PostGroupCreate)
Create a group.
1. [POST /group/delete.json](http://theopenphotoproject.org/documentation/api/PostGroupDelete)
Delete a group.
1. [POST /group/update.json](http://theopenphotoproject.org/documentation/api/PostGroupUpdate)
Update a group.
#### Webhook endpoints
1. [POST /webhook/subscribe](http://theopenphotoproject.org/documentation/api/PostWebHookSubscribe)
Update an eixsting webhook.
1. [GET /webhook/:id/view.json](http://theopenphotoproject.org/documentation/api/GetWebhook)
Get a user's webhook by id.
1. [POST /webhook/:id/delete.json](http://theopenphotoproject.org/documentation/api/PostWebHookDelete)
Delete an existing webhook.

86
docs/contribute/Readme.markdown Normal file
View file

@ -0,0 +1,86 @@
Contributing to The OpenPhoto Project
=======================
## TL;DR
Alright, we get it. You'd rather code than read. Here's the checklist.
1. Fork the <a href="https://github.com/photo/frontend">frontend</a> repository. <a href="http://help.github.com/fork-a-repo/">More info on forking</a>.
1. Follow one of our <a href="/documentation">guides</a> on setting the software up.
1. Get coding!
1. <a href="/contribute/frontend">More details</a> if you need them.
<div></div>
# replace {username} with your github username
# clone your repository locally and cd into the new directory
user@ git clone git@github.com:{username}/frontend.git
user@ cd frontend
# add the official openphoto repository as upstream
user@[frontend] git remote add upstream git://github.com/photo/frontend.git
user@[frontend] git pull upstream
# all active development happens in the development branch
# as a result it maybe unstable so you can always use master which should work
user@[frontend] git checkout development
# make your changes and commit them locally
user@[frontend] git commit -m 'Lots of details! Closes #123'
user@[frontend] git push origin development
Now you're ready to <a href="http://help.github.com/send-pull-requests/">send a pull request</a>!
## There's a spot for everyone to be a part of something BIG
Hear ye, hear ye! <a href="#developers">Developers</a>, <a href="#designers">designers</a>, <a name="#powerusers">power users</a>, <a href="#copywriters">copywriters</a>, <a href="#community">community managers</a>, <a href="#translators">translators</a>, and anyone else who wants to help. If you want to contribute to The OpenPhoto Project, the good news is that there's probably a place where we could use your help!
It's easy to get in touch with us, as many of us hang out in #openphoto on Freenode. Come in and <a href="http://webchat.freenode.net/">chat with us</a>. We're happy to answer any questions you might have.
Here's a full list of ways to contact us:
* <a href="http://webchat.freenode.net/">Chat with us on IRC #openphoto on freenode.net</a>
* <a href="http://groups.google.com/group/openphoto">Join our mailing list on Google Groups</a>
* <a href="https://github.com/photo">Submit bugs on Github</a>
* <a href="https://github.com/photo/frontend">Web or API</a>
* <a href="https://github.com/photo/mobile-ios">iPhone app</a>
* <a href="https://github.com/photo/mobile-android">Android app</a>
* <a href="https://github.com/photo/openphoto-php">PHP bindings</a>
* <a href="https://github.com/photo/openphoto-ruby">Ruby bindings</a>
* <a href="https://github.com/photo/openphoto-python">Python bindings</a>
* <a href="https://github.com/photo/openphoto-java">Java bindings</a>
* <a href="http://twitter.com/photo">Follow us on Twitter</a>
* <a href="http://www.facebook.com/OpenPhoto">Like us on Facebook</a>
<a name="developers"></a>
## Developers and Designers
There's a lot of engineering goodness to be had here. We've got code written in HTML, CSS, JavaScript, PHP, Ruby, Python, Java and Objective-C. If you're interested helping out with a specific part of OpenPhoto, then fork the repository and send us some pull requests. If you don't know exactly where to begin, then contact us. We're more than happy to help you get started.
That being said, the largest part of the code base is the <a href="https://github.com/photo/frontend">frontend</a> repository. It houses the web interface, as well as the REST API which every other repository communicates to. This repository is also the one we've got a formal process to contribute to with unit tests and the works.
<a href="http://theopenphotoproject.org/contribute/frontend" class="btn danger">Start contributing</a>
<a name="copywriters"></a>
## Copywriters and Wordsmiths
If you've got a gift with words we're in desperate need of your help. Much of the community consists of engineers and well, we suck at taking complex ideas and distilling them into small and easy to understand sentences.
The best way to get started is to read the copy at <a href="http://theopenphotoproject.org">The OpenPhoto Project</a>'s website. Some of it is technical, like the documentation, but much of it is also trying to explain why users should care about what we're building. Wherever your passion lies, we will definitely appreciate the help.
Everything can be found in the <a href="https://github.com/photo/community">community</a> repository for the non-technical bits or the <a href="https://github.com/photo/frontend">frontend</a> repository for the documentation.
We have <a href="https://github.com/photo/frontend/issues?labels=Documentation&page=1&state=open">issues tagged documentation</a> on Github, but just about every area of the site needs some attention. You can open an issue for the appropriate repository or fork it and send us a pull request. If you have any questions, let us know using one of the channels above.
<a name="powerusers"></a>
## Power Users
Do you know OpenPhoto inside out, including all its little quirks? Then we need you! A lot of people ask questions about OpenPhoto on our mailing list or on IRC, so hang out on those channels and help someone out. This is a great way to get to know other OpenPhoto users. You can also help out by filing Github issues when you find bugs and discussing them on our issues board.
<a name="community"></a>
## Community Managers and Social Media
Send an email to <a href="mailto:hello@openphoto.me">hello@openphoto.me</a> or <a href="https://twitter.com/openphoto">@mention us</a> on Twitter if you'd like to help with Community Management or Social Media.
<a name="translators"></a>
## Translators
We want to make The OpenPhoto Project available for everyone. This means translating it into as many languages as possible. If you're interested in helping us out, then drop an email to <a href="mailto:hello@openphoto.me">hello@openphoto.me</a> and we'll be in touch once we have our translation platform ready.

106
docs/contribute/frontend.markdown Normal file
View file

@ -0,0 +1,106 @@
Contributing to the Web and API components
=======================
## Up and contributing in under 5 minutes
So what do you need to get started?
A computer! Once you've secured one of those all you need is a Github account. It helps to have a locally installed version of the frontend repository to test your changes. We've got <a href="http://theopenphotoproject.org/documentation">lots of guides</a> to help you get started. If you're updating any of the PHP code you should get PHPUnit as well.
pear channel-discover pear.phpunit.de
pear channel-discover pear.bovigo.org
pear install pear.phpunit.de/PHPUnit
pear install bovigo/vfsStream-beta
# problems? check the links below
# http://www.phpunit.de/manual/3.6/en/installation.html
# http://stackoverflow.com/questions/3301300/setting-up-phpunit-on-osx
Now that you've got:
* A computer
* <a href="https://github.com">A GitHub account</a>
* An <a href="http://theopenphotoproject.org/documentation">installation of the frontend repository</a>
* <a href="http://www.phpunit.de/manual/3.6/en/installation.html">PHPUnit</a>,
let's continue.
## Deciding what to fix
We've added a _Beginner_ label to issues that don't touch some of the more sensitive parts of the code. We've additionally added _CSS_, _JavaScript_, and _PHP_ labels so you can narrow it down to exactly what you're interested in.
* <a href="https://github.com/photo/frontend/issues?labels=Beginner&sort=created&direction=desc&state=open&page=1">All Beginner issues</a>
* <a href="https://github.com/photo/frontend/issues?labels=Beginner%2CCSS&sort=created&direction=desc&state=open&page=1">Beginner + CSS issues</a>
* <a href="https://github.com/photo/frontend/issues?labels=Beginner%2CJavaScript&sort=created&direction=desc&state=open&page=1">Beginner + JavaScript issues</a>
* <a href="https://github.com/photo/frontend/issues?labels=Beginner%2CPHP&sort=created&direction=desc&state=open&page=1">Beginner + PHP issues</a>
## Things to keep in mind while you code
Here's what your code should adhere to:
* Unit tests should pass (more on that in the next section)
* Spacing matters: two spaces, no tabs
* Commits should reference an issue number (more on that below)
* Comment your code so future developers can tell what's going on
* Curly braces go on their own line. For example:
````php
if(condition)
{
statement 1;
statement 2;
}
// or
if(condition)
only statement;
````
All in all, we recognize that everyone has a different style and level of experience, and we welcome all pull requests.
## Testing that your change didn't break anything
Once you've made your change and verified it does what it should it's time to make sure it's not doing something it shouldn't. This is as easy as a single command.
phpunit -c src/tests/phpunit.xml
............................................................ 60 / 311
............................................................ 120 / 311
............................................................ 180 / 311
...............I....................................I....... 240 / 311
........I......................I............................ 300 / 311
...........
Time: 2 seconds, Memory: 16.50Mb
OK, but incomplete or skipped tests!
Tests: 311, Assertions: 661, Incomplete: 4.
Those `I`s are okay but you shouldn't see any `E`s or `F`s and definitely look for the `OK` message at the end. If all the tests pass then you're good to go and can commit your changes.
You can automate this by adding a pre-commit hook. Just copy <a href="https://github.com/photo/frontend/blob/master/documentation/hooks/pre-commit">this file</a> into your `.git/hooks` directory or run the command below.
wget --no-check-certificate https://raw.github.com/photo/frontend/master/documentation/hooks/pre-commit -O .git/hooks/pre-commit
chmod u+x .git/hooks/pre-commit
Now every time you make a commit it will first run the unit tests automatically.
## Committing your code
When committing your code it's important to reference the GitHub issue you're fixing. You can do it by adding a _#_ followed by the issue number.
# To simply reference an issue with a commit do this
git commit -m 'Addressing the foobar component but not yet finished. #123'
# To commit and close an issue do this
git commit -m 'Fixing the most annoying bug ever. Closes #123'
Be descriptive, it helps a ton. Once you've committed your code it's time to push it to GitHub.
git push origin master
## Getting your change into the OpenPhoto branch
To get your change merged into the official OpenPhoto branch, submit a pull request. <a href="http://help.github.com/send-pull-requests/">GitHub's tutorial</a> is better than anything we could do so we'll link to it.
It makes everyone's lives easier if you can remember to issue the pull request to OpenPhoto's development branch. If you forget, no big deal. The important thing is we get your change and your awesomeness can be merged into everyone else's awesomeness.
## Help! I'm stuck and have questions
If you have questions we're always around to help. We've got several contact options listed on the <a href="http://theopenphotoproject.org/contribute">contribute</a> page.

20
docs/faq/AccountManagement.markdown Normal file
View file

@ -0,0 +1,20 @@
Account Management
=======================
## How do I create an account?
Visit http://openphoto.me and click the Sign Up button. Select a username for your OpenPhoto site along with a password.
## How do I log in?
You can do this in two ways: through the main openphoto.me site or through your own site. Click Sign In, and then enter your email address and password.
## How can I retrieve a lost password?
Go to the Sign In page and click "Forgot Password" next to the password entry field. Enter the email address you signed up with and click Submit. You'll receive a link where you can reset your password.
## Can I change the email I signed up with?
Not at this time, no. We're working on it.
## Can I change my password?
Yes. When you sign in, click "Forgot password?" and enter your email address. You'll get a link to reset your password as if you had forgotten it.
## How do I delete my account?
We're sad to see you go. Right now account deletion is manual, so email support@openphoto.me and we'll delete your account for you. Before you delete your account, make sure to migrate your photos to an external account that you control. You can do that at https://openphoto.me/migrate

14
docs/faq/Faq.markdown Normal file
View file

@ -0,0 +1,14 @@
Frequently Asked Questions
=======================
Here are some questions that people have about The OpenPhoto Project. If you have one that's not on this list send an <a href="mailto:openphoto@googlegroups.com">email</a>.
### What is OpenPhoto?
OpenPhoto is a photo hosting service that puts you in control. It lets you import, archive, and organize your photos on OpenPhoto's servers or your personal cloud accounts such as Dropbox or Amazon S3. Your choice.
It's the photo service you never knew you wanted until it existed.
### What makes OpenPhoto different than Flickr/Smugmug/Instagram/any other photo site?
Normally you pay one company to store your photos and to provide services to share them. This means that you can't do much if they raise their prices or shut down their site. If you decide you don't like their site anymore, the process of leaving and setting up somewhere new can be long and frustrating if you care about keeping your photos.
With OpenPhoto you can switch between services, use more than one at a time, or stop using the service without losing a single photo.

24
docs/faq/Glossary.markdown Normal file
View file

@ -0,0 +1,24 @@
OpenPhoto / Glossary
=======================
The OpenPhoto stack consists of various components. Below is a glossary of all the terms you need to know so you can understand the overall system.
1. **Amazon S3**
[Amazon S3][s3] stands for Simple Storage Service.
1. **Amazon SimpleDb**
[Amazon SimpleDb][simpledb] is a non-relational database system.
1. **Data Source**
The Data Source stores all textual data for a given user. Each user's Data Source may be different. The default Data Source is data.openphoto.me as a CNAME to [Amazon SimpleDb][simpledb].
1. **File System**
The File System stores all high and low resolution photos for a given user. Each user's File System may be different. The default File System is file.openphoto.me as a CNAME to [Amazon S3][s3].
1. **Adapter**
Adapters are middleware that allows the base system to communicate with various Data Sources and File Systems. Adapters exist for [Amazon S3][s3] and [Amazon SimpleDb][simpledb].
1. **Open Photo API**
[The Open Photo API][openphotoapi] which this software is built on and also allows others to build applications on top of.
[openphotoapi]: documentation/api
[aws]: http://aws.amazon.com/
[s3]: http://aws.amazon.com/s3/
[simpledb]: http://aws.amazon.com/simpledb/

13
docs/faq/MobileApps.markdown Normal file
View file

@ -0,0 +1,13 @@
The OpenPhoto Mobile Apps
=======================
## What phones are supported?
OpenPhoto has mobile apps for iPhone and Android. You can download them in the App Store (iOS) or Play Store (Android).
## What can I do with the OpenPhoto mobile apps?
* Create an OpenPhoto account
* Upload photos to your OpenPhoto site
* Add titles, descriptions, privacy settings, and tags
* Share photos via email, Twitter, and Facebook
* Add filters to your photos (iOS)

106
docs/faq/PhotoGeneration.markdown Normal file
View file

@ -0,0 +1,106 @@
How photos are generated
=======================
### Overview of how and when versions of photos are generated
By default, when a photo is uploaded there are two versions of that photo which are stored. The original version (`pathOriginal`) and a slightly lower resolution version (`pathBase`).
The API is capable of returning URLs for any size version of every photo. This is acheived by passing in a parameter named `returnSizes` to the [GET Photos](http://theopenphotoproject.org/documentation/api/GetPhotos) and [GET Photo](http://theopenphotoproject.org/documentation/api/GetPhoto) APIs. This ensures that the response for the photo(s) will include a URL for the size(s) you specify. Here is an example.
curl "http://current.openphoto.me/photo/63.json?returnSizes=123x123"
This call returns the following response.
{
"code" : 200,
"message" : "Photo 63",
"result" : {
"appId" : "current.openphoto.me",
"creativeCommons" : "BY-NC",
"dateTaken" : "1313010850",
"dateTakenDay" : "10",
"dateTakenMonth" : "08",
"dateTakenYear" : "2011",
"dateUploaded" : "1313010853",
"dateUploadedDay" : "10",
"dateUploadedMonth" : "08",
"dateUploadedYear" : "2011",
"description" : "",
"exifCameraMake" : "",
"exifCameraModel" : "",
"hash" : "20d64642f09befc4004c22269e698e6e43475963",
"height" : "1936",
"host" : "opmecurrent.s3.amazonaws.com",
"id" : "63",
"latitude" : "",
"longitude" : "",
"path123x123" : "http://current.openphoto.me/photo/63/create/1a7f0/123x123.jpg",
"path200x200" : "http://opmecurrent.s3.amazonaws.com/custom/201108/1313010849-opmeTbrBki_200x200.jpg",
"pathBase" : "/base/201108/1313010849-opmeTbrBki.jpg",
"pathOriginal" : "/original/201108/1313010849-opmeTbrBki.jpg",
"permission" : "1",
"size" : "1513",
"status" : "1",
"tags" : [ ],
"title" : "Gulf Shores, AL",
"views" : "0",
"width" : "2592"
}
}
The most important keys in the response are `path123x123` and `path200x200`. Either of these URLs will correctly render the photo in the respective size. Notice, however, that the `path123x123` hostname is different from `path200x200`. This is important because this implies that a _123x123_ version of the photo doesn't exist and the API host needs to generate it. The following url will generate the correct version of the photo, store it to the proper file system, saves it to the database and returns it with a content-type of _image/jpeg_.
http://current.openphoto.me/photo/63/create/1a7f0/123x123.jpg
It's important to realize that the photo isn't generated and stored until this URL is called. This typically happens when the browser tries to display this photo. Once that has happened then the _123x123_ version exists both in the database and file system and calling the same API again returns a different URL for `path123x123`.
{
"code" : 200,
"message" : "Photo 63",
"result" : {
"appId" : "current.openphoto.me",
"creativeCommons" : "BY-NC",
"dateTaken" : "1313010850",
"dateTakenDay" : "10",
"dateTakenMonth" : "08",
"dateTakenYear" : "2011",
"dateUploaded" : "1313010853",
"dateUploadedDay" : "10",
"dateUploadedMonth" : "08",
"dateUploadedYear" : "2011",
"description" : "",
"exifCameraMake" : "",
"exifCameraModel" : "",
"hash" : "20d64642f09befc4004c22269e698e6e43475963",
"height" : "1936",
"host" : "opmecurrent.s3.amazonaws.com",
"id" : "63",
"latitude" : "",
"longitude" : "",
"path123x123" : "http://opmecurrent.s3.amazonaws.com/custom/201108/1313010849-opmeTbrBki_123x123.jpg",
"path200x200" : "http://opmecurrent.s3.amazonaws.com/custom/201108/1313010849-opmeTbrBki_200x200.jpg",
"pathBase" : "/base/201108/1313010849-opmeTbrBki.jpg",
"pathOriginal" : "/original/201108/1313010849-opmeTbrBki.jpg",
"permission" : "1",
"size" : "1513",
"status" : "1",
"tags" : [ ],
"title" : "Gulf Shores, AL",
"views" : "0",
"width" : "2592"
}
}
The URL for `path123x123` now points to a static resource.
You can specify multiple sizes for the `returnSizes` delimited by commas.
curl "http://current.openphoto.me/photo/63.json?returnSizes=123x123,300x300xBW"
### Understanding options for returnSizes
The `returnSizes` parameter takes values in the form of _WxH[[xA]xB]_ which means it starts with a numeric _width_ and _height_. The most simple form is limited to specifying just a _width_ and _height_. This looks like `200x200` or `125x300`.
Additional options include `CR` and `BW`. `CR` tells the API to crop the photo to be exactly _width_ by _height_. It does a center crop and minimizes the portion of the photo that is cropped. `BW` applies a greyscale filter to the photo. `100x100xCRxBW` means the photo will have a key of `path100x100xCRxBW` and will be exactly _100_ by _100_, cropped and greyscale.
For more information on the `returnSizes` parameter see our [documentation on returnSizes](http://theopenphotoproject.org/documentation/faq/ReturnSizes).

32
docs/faq/PhotoManagement.markdown Normal file
View file

@ -0,0 +1,32 @@
Photo Management
=======================
## How do I upload a photo?
Go to your OpenPhoto site (it'll look like yourusername.openphoto.me) and click Upload. Click Add Photos and add the photos you'd like to upload. You can also add attributes that'll apply to all the photos uploaded in that batch, such as a tag, an album, a privacy setting, or a license.
## How do I delete a photo?
Visit Photos under the Manage dropdown menu at your OpenPhoto site while logged in. From there, hover over the photo(s) you want to delete and click the checkmark that appears. Click Batch Edit and select Delete.
## What are albums? How do they work?
An album is a collection of photos grouped around a theme of your choice. This lets you share many photos with friends or browse your own photos more easily. Albums can be public or private on your albums page.
## How do I create an album?
While you're logged into your OpenPhoto site, visit Albums under the Manage menu. Enter the name of your album under the Create Album section and click Create.
## How do I add a photo to an album?
You can add a photo to an album by editing an individual photo's details or batch editing photos.
## How do I edit a photo's details?
Visit the photo's page and click "Edit Details". Then you can edit the title, description, tags, location, albums, groups, privacy, and license.
## How do I edit multiple photos at once?
Visit Photos under the Manage dropdown menu at your OpenPhoto site while logged in. From there, hover over the photo(s) you want to edit and click the checkmark that appears. Click Batch Edit and select the detail you want to edit, change the detail, and click Submit.
## What are groups? How do they work?
Groups let you share a photo with certain people without exposing the photo to the entire Web. Want to share photos from that party last week but don't want just anyone seeing them? Add the photos to a private group that only your friends have access to.
## How do I add a friend to a group?
Visit Groups under the Manage menu and create a name for a group. From there you can add your friends by email address. They can log in with Mozilla Persona or Facebook to view the photos.
## How do I add a photo to a group?
When you upload a photo, you can select a group for the photo to be part of. This is completely optional. You can also change the group(s) a photo is part of at the Manage Photos menu.

34
docs/faq/ReturnSizes.markdown Normal file
View file

@ -0,0 +1,34 @@
Getting specific sizes of a photo
=======================
### Understanding the `returnSizes` parameter and how to use it
For the [GET /photo/view.json](http://theopenphotoproject.org/documentation/api/GetPhoto) and [GET /photos/list.json](http://theopenphotoproject.org/documentation/api/GetPhotos) you can pass in an optional `returnSizes` parameter.
If you need a path to a photo then you'll want to make sure you pass this parameter in else your response won't contain any URLs.
We also have a more detailed look at how [photos are generated](http://theopenphotoproject.org/documentation/faq/PhotoGeneration).
### Specifying the width and height of photos you want
The first decision you need to make is the size or sizes of photos you want in the response.
You'll specify this as the initial part of the `returnSizes` parameter.
If you want a single size for the photo of width `W` and height `H` then you will want to use the following.
returnSizes=WxH
If you want multiple sizes for the photo of widths `W1` and `W2` and heights `H1` and `H2` then use the following.
returnSizes=W1xH1,W2xH2
#### Maintaining aspect ratio and cropping
By default the aspect ratio of every photo is maintained.
That means if you request a `200x200` version of a photo that's originally `800x600` then the resulting image will be _200px_ wide and _150px_ tall.
If you want the same photo to be exactly _200px_ by _200px_ then you can add an optional value to `returnSizes`.
returnSizes=200x200xCR
Adding `xCR` means that the photo will be exactly _200px_ by _200px_ and cropped from the center retaining as much of the photo as possible.
### Accessing the paths in the response
The name of the URL attribute in the response is, by convention, `pathWxH` where `WxH` is the value passed in to returnSizes.

21
docs/faq/SelfHostedFaq.markdown Normal file
View file

@ -0,0 +1,21 @@
## Self-Hosted OpenPhoto FAQ
### How can I install OpenPhoto?
We have lots of guides to help you through the installation process. <a href="http://theopenphotoproject.org/documentation">Check them out here</a>. We welcome <a href="http://github.com/photo/frontend">contributions on Github</a> if you see one that's incomplete.
### Can I install OpenPhoto to a subdirectory of my site?
Not yet, but it's on our wishlist.
### How does support for multiple users work?
We support multiple users through separate domains. <a href="https://github.com/photo/frontend/issues/318">See this issue on why it works that way.</a>
### Is your mobile app available for self-hosted users?
Yes! Download the app <a href="http://itunes.com/apps/theopenphotoapp">for iOS</a> or <a href="https://play.google.com/store/apps/details?id=me.openphoto.android.app">Android</a>.
### I just changed my domain name. Why am I getting prompted for new settings?
This is normal. OpenPhoto configs are bound to a site, not a server. Since a site is defined by its hostname, you can have multiple sites on one host provided that they have different hostnames. So go ahead and change your settings.
### I encountered a security issue in OpenPhoto. What's the best way to let you know?
<a href="https://github.com/photo/frontend/issues">Report it as an issue at Github</a>. If you don't feel comfortable exposing a security issue, reach out to someone on the core team and email us individually.
### Something broke. How do I let you know?
Check <a href="https://github.com/photo/frontend/issues">our issue tracker at Github</a> first; if the issue you're encountering isn't already there, then start a new issue and describe what you ran across.

15
docs/faq/Storage.markdown Normal file
View file

@ -0,0 +1,15 @@
Photo Storage
=======================
## Where can I store my photos?
Right now OpenPhoto supports Amazon S3, Box.com, Dropbox, CX.com, and DreamHost DreamObjects.
## How do I switch where my photos are stored?
Visit http://openphoto.me/migrate while logged in, select where you'd like your photos to go, and follow the instructions.
## How can I import my photos?
You can import your photos through the Upload photos page when you're logged into OpenPhoto. At the bottom of the Upload photos page are links to import photos from Flickr, Facebook, and Instagram. Select the site(s) you'd like to import from and follow the instructions.
## Can I keep uploading to another photo site and have that photo automatically show up in OpenPhoto?
Not directly through OpenPhoto, but you can use sites like ifttt or Pi.pe that will automatically upload a picture to OpenPhoto when you upload a picture somewhere else (or vice versa).

31
docs/guides/Guides.markdown Normal file
View file

@ -0,0 +1,31 @@
OpenPhoto / Guides
=======================
#### OpenPhoto, a photo service for the masses
### Step by step installation guides
Follow these step by step guides to get OpenPhoto installed on your server or laptop.
1. [Ubuntu with Apache][guideinstallubuntuapache]
1. [OSX using MacPorts][guideinstallosxmacports]
1. [Amazon EC2 OpenPhoto AMI][guideinstallamazonec2]
1. [SUSE][guideinstallsuse]
1. [Ubuntu with Cherokee][guideinstallubuntucherokee]
1. [Fedora 16 with Apache][guideinstallfedora16apache]
### The quick and dirty installation
You'll probably want to follow one of the guides above but setting up OpenPhoto is as easy as one command.
curl https://raw.github.com/photo/frontend/master/documentation/guides/InstallationUbuntuApache.sh | /bin/bash
That's it. View the [source of the installer][guideinstallcli] or [watch a screencast][screencast] of it.
[guideinstallubuntuapache]: InstallationUbuntuApache.markdown
[guideinstallosxmacports]: InstallationOSXMacports.markdown
[guideinstallsuse]: InstallationSUSE.markdown
[guideinstallubuntucherokee]: InstallationUbuntuCherokee.markdown
[guideinstallamazonec2]: InstallationUsingOpenPhotoEC2-AMI.markdown
[guideinstallcli]: InstallationUbuntuApache.sh
[screencast]: http://youtu.be/2QXtHPkO8eQ
[guideinstallfedora16apache]: InstallationFedora16Apache.markdown

77
docs/guides/InstallationDreamhost.markdown Normal file
View file

@ -0,0 +1,77 @@
# OpenPhoto / Installation for Dreamhost
#### OpenPhoto, a photo service for the masses
## Installation on Dreamhost
This guide instructs you on how to install OpenPhoto on Dreamhost.
The guide assumes a MySQL installation using the local filesystem for photo storage.
*OpenPhoto should be installed in the root directory of a domain or subdomain.*
Variables:
- *YOURDOMAIN*:the subdomain or domain for hosting OpenPhoto
- *YOURNAME*: your Dreamhost username
- *OpenPhotoRoot*: the root directory for OpenPhoto (e.g., ~/openphoto)
### Steps
1. Download and install OpenPhoto
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf openphoto.tar.gz
mv openphoto-frontend-* OpenPhotoRoot
1. Create directories
mkdir OpenPhotoRoot/src/html/assets/cache
chmod 775 OpenPhotoRoot/src/html/assets/cache
mkdir OpenPhotoRoot/src/html/photos
chmod 775 OpenPhotoRoot/src/html/photos
mkdir OpenPhotoRoot/src/userdata
chmod 775 OpenPhotoRoot/src/userdata
1. Configure the subdomain or domain.
Go to the [Dreamhost control panel for managing domains](https://panel.dreamhost.com/index.cgi?tree=domain.manage)
Domain settings:
- Select the *Fully Hosted* portion of the configuration panel.
- *Do you want the www in your URL?* Select "Leave it alone"
- *Web directory:* Set to *OpenPhotoRoot*/src/html
- *PHP mode:* Select the latest version of PHP (use FastCGI configuration)
1. Go to the [Dreamhost control panel for managing databases](https://panel.dreamhost.com/index.cgi?tree=goodies.mysql)
and create a new database and a new user for the database. Remember the hostname (the default should be fine), database name, user name, and password, since you'll need this information during the setup.
1. After waiting a sufficient amount of time for the subdomain name to propagate, use the browser to connect to the new subdomain. You should see a setup page for OpenPhoto which will allow you to configure your OpenPhoto project.
- *Select Database:* MySQL
- *Select File System:* Local filesystem
- *Enter your local file system credentials:* /home/USERNAME/OpenPhotoRoot/src/html/photos
- *File system hostname for download URL (Web accessible w/o "http://"):* YOURDOMAIN.com/photos
### Troubleshooting
#### Setup page looks strange (black and white, unstyled)
If the setup page is not colorful and well formatted, then the css and javascript files are most likely not being loaded. Possible causes:
- Web directory root is not properly set (check control panel for the subdomain)
- src/html/assets/cache directory is not writeable by Apache (check permissions)
#### Error setting up the database
Double check all the parameters. Open the Dreamhost control panel for databases.
### Launching your OpenPhoto site
Now you're ready to launch your OpenPhoto site. Point your browser to your host and you'll be taken to a setup screen.
Once you complete the three steps your site will be up and running.
**ENJOY!**

113
docs/guides/InstallationFedora16Apache.markdown Normal file
View file

@ -0,0 +1,113 @@
OpenPhoto / Installation for Fedora 16 + Apache
=======================
#### OpenPhoto, a photo service for the masses
## OS: Linux Fedora 16
This guide instructs you on how to install OpenPhoto on a Fedora server.
----------------------------------------
### Prerequisites
#### Database and File System Options
##### MySql
You'll need to provide credentials for a MySql database. If the database doesn't already exist it will be created. If the user doesn't have `CREATE DATABASE` permissions then make sure it's already created.
##### AWS
If you're going to use AWS services then You'll need to be signed up for them.
* http://aws.amazon.com/simpledb/
* http://aws.amazon.com/s3/
#### Server Packages and Modules
Once you've confirmed that your cloud account is setup you can get started on your server. For that you'll need to have _Apache_, _PHP_ and _curl_ installed with a few modules.
yum groupinstall 'Development Tools'
yum groupinstall 'Development Libraries'
yum install httpd httpd-devel php php-devel php-common php-curl php-gd php-mcrypt pcre pcre-devel ImageMagick php-magickwand php-pecl-imagick ImageMagick-devel php-pear php-mysql
pecl install apc
echo "extension=apc.so" > /etc/php.d/apc.ini
pecl install oauth
echo "extension=oauth.so" > /etc/php.d/oauth.ini
----------------------------------------
### Installing OpenPhoto
Download and install the source code. We recommend `/var/www/yourdomain.com` but you can use any directory you'd like.
#### Using git clone
The _Apache 2_ user in Fedora 16 is `apache` so run the following commands to take ownership of the web files.
yum install git
git clone git://github.com/photo/frontend.git /var/www/yourdomain.com
chown -R apache: /var/www/yourdomain.com
Assuming that this is a development machine you only need to make the config writable by the user Apache runs as. Most likely `apache`.
mkdir /var/www/yourdomain.com/src/userdata
mkdir /var/www/yourdomain.com/src/html/photos
mkdir /var/www/yourdomain.com/src/html/assets/cache
chown apache: /var/www/yourdomain.com/src/userdata
chown apache: /var/www/yourdomain.com/src/html/photos
chown apache: /var/www/yourdomain.com/src/html/assets/cache
### Setting up Apache and PHP
#### Apache
You'll need to copy the sample virtual host configuration file from the source to `/etc/httpd/conf.d/`.
cp /var/www/yourdomain.com/src/configs/openphoto-vhost.conf /etc/httpd/conf.d/openphoto.conf
You'll need to replace instances of `/path/to/openphoto/html/directory` with `/var/www/yourdomain.com/src/html` or wherever you placed the code.
Edit `/etc/httpd/conf/httpd.conf` and ensure the following modules are enabled: _rewrite_, _deflate_, _expires_, _headers_. Here are the corresponding lines to the enabled apache modules in `httpd.conf`.
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule deflate_module modules/mod_deflate.so
LoadModule expires_module modules/mod_expires.so
LoadModule headers_module modules/mod_headers.so
By default, any access to ini files is denied with a "Not Found" 404 HTTP code. To enable a 404, or Forbidden return code, change the following lines in the virtual host file.
Uncomment:
# 403 Forbidden for ini files
#RewriteRule \.ini$ - [F,NC]
Comment:
# 404 Not Found for ini files
AliasMatch \.ini$ /404
### PHP
You should also verify that your `php.ini` file has a few important values set correctly.
vi /etc/php.ini
Search for the following values and make sure they're correct.
file_uploads = On
upload_max_filesize = 16M
post_max_size = 16M
Ensure that `/etc/php.d/apc.ini` and `/etc/php.d/oauth.ini` exist and that the php extensions are enabled.
Now you're ready to restart apache and visit the site in your browser.
service httpd restart
### Launching your OpenPhoto site
Now you're ready to launch your OpenPhoto site. Point your browser to your host and you'll be taken to a setup screen. You'll need your cloud account credentials to continue.
Once you complete the 3 steps your site will be up and running and you'll be redirected there. The _setup_ screen won't show up anymore. If for any reason you want to go through the setup again you will need to delete the generated config file and refresh your browser.
rm /var/www/yourdomain.com/src/userdata/configs/yourdomain.com.ini
**ENJOY!**

163
docs/guides/InstallationFreeBSDNginx.markdown Normal file
View file

@ -0,0 +1,163 @@
OpenPhoto / Installation for FreeBSD + Nginx
=======================
#### OpenPhoto, a photo service for the masses
## OS: FreeBSD 9.0+
This guide instructs you on how to install OpenPhoto on an FreeBSD Server
----------------------------------------
### Prerequisites
#### Database and File System Options
##### MySql
You'll need to provide credentials for a MySql database. If the database doesn't already exist it will be created. If the user doesn't have `CREATE DATABASE` permissions then make sure it's already created.
##### AWS
If you're going to use AWS services then You'll need to be signed up for them.
* http://aws.amazon.com/simpledb/
* http://aws.amazon.com/s3/
#### Server Packages and Modules
Once you've confirmed that your cloud account is setup you can get started on your server. For that you'll need to have _NGinx_, _PHP-FPM_ and _CURL_ installed with a few modules.
##### Install Nginx
Compile Nginx with :
HTTP_MODULE
HTTP_CACHE_MODULE
HTTP_GZIP_STATIC_MODULE
HTTP_REWRITE_MODULE
HTTP_UPLOAD_MODULE
HTTP_UPLOAD_PROGRESS
cd /usr/ports/www/nginx
make config install clean distclean
##### Install php5
Compile php5 with :
CLI
FPM
SUHOSIN
MULTIBYTE
MAILHEAD
cd /usr/port/lang/php5-extentions
make config install clean distclean
##### Install php5 extentions
Compile php5 extentions with :
BZ2
CALENDAR
CTYPE
CURL
DOM
FILEINFO
FILTER
GD
HASH
ICONV
JSON
MBSTRING
MCRYPT
OPENSSL
PDF
PHAR
POSIX
SESSION
SIMPLEXML
TOKENIZER
XML
XMLREADER
XMLWRITER
XSL
ZLIB
cd /usr/port/lang/php5-extentions
make config install clean distclean
And if you are going to use MySQL compile `php5-extentions` with `MYSQL MYSQLI`.
There are also a few optional but recommended packages and modules.
/usr/ports/net/pecl-oauth
/usr/ports/graphics/pecl-imagick
/usr/ports/graphics/exiftran
----------------------------------------
### Installing OpenPhoto
Download and install the source code. We recommend `/usr/local/www/yourdomain.com` but you can use any directory you'd like.
#### Using git clone
pkg_add -r git-core
git clone git://github.com/photo/frontend.git /usr/local/www/yourdomain.com
#### Using tar
cd /usr/local/www
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf openphoto.tar.gz
mv openphoto-frontend-* yourdomain.com
Assuming that this is a development machine you only need to make the config writable by the user Apache runs as. Most likely `www`.
mkdir /usr/local/www/yourdomain.com/src/userdata
mkdir /usr/local/www/yourdomain.com/src/html/photos
mkdir /usr/local/www/yourdomain.com/src/html/assets/cache
chown www:www /usr/local/www/yourdomain.com/src/userdata
chown www:www /usr/local/www/yourdomain.com/src/html/photos
chown www:www /usr/local/www/yourdomain.com/src/html/assets/cache
----------------------------------------
### Setting up NGinx and PHP
#### NGinx
You'll need to copy the sample virtual host configuration file from the source to `/etc/nginx/sites-enabled`.
cp /usr/local/www/yourdomain.com/src/configs/openphoto-nginx.conf /usr/local/etc/nginx/sites-enabled/openphoto
You'll need to replace:
* The host name (yourdomain.com)
* The path where OpenPhoto is installed (/usr/local/www/yourdomain.com/src/html/)
/usr/local/etc/nginx/sites-enabled/openphoto
### PHP
You should also verify that your `php.ini` file has a few important values set correctly.
vi /usr/local/etc/php.ini
Search for the following values and make sure they're correct.
file_uploads = On
upload_max_filesize = 16M
post_max_size = 16M
Now you're ready to restart apache and visit the site in your browser.
/usr/local/etc/rc.d/php-fpm restart
/usr/local/etc/rc.d/nginx restart
### Launching your OpenPhoto site
Now you're ready to launch your OpenPhoto site. Point your browser to your host and you'll be taken to a setup screen. You'll need your cloud account credentials to continue.
Once you complete the 3 steps your site will be up and running and you'll be redirected there. The _setup_ screen won't show up anymore. If for any reason you want to go through the setup again you will need to delete the generated config file and refresh your browser.
rm /usr/local/www/yourdomain.com/src/userdata/configs/yourdomain.com.ini
**ENJOY!**

165
docs/guides/InstallationFreeBSDNginx_FR.markdown Normal file
View file

@ -0,0 +1,165 @@
OpenPhoto / Installation sous FreeBSD + Nginx
=======================
#### OpenPhoto, un service de photo pour les masses
## OS: FreeBSD 9.0+
Ce guide vous explique comment installer sur un serveur OpenPhoto sous FreeBSD avec Nginx
----------------------------------------
### Pré-requis
#### Bases de données et Cloud
##### MySQL
You'll need to provide credentials for a MySql database. If the database doesn't already exist it will be created. If the user doesn't have `CREATE DATABASE` permissions then make sure it's already created.
OpenPhoto necessite une base de donnée. Si la base n'existe pas et que l'utilisateur MySQL n'a pas le droit d'executer la commande `CREATE DATABASE`, assurez vous que la base existe deja
##### Amazon Web Services
Si vous allez utiliser 'Amazon Web Services', vous aurez besoin de vous y identifier.
* http://aws.amazon.com/simpledb/
* http://aws.amazon.com/s3/
#### Configuration de l'environement.
Configuration et compilation de _NGinx_ _PHP-FPM_ et _CURL_ avec quelques modules.
##### _NGinx_
Compiler _NGinx_ avec les options ci-dessous :
HTTP_MODULE
HTTP_CACHE_MODULE
HTTP_GZIP_STATIC_MODULE
HTTP_REWRITE_MODULE
HTTP_UPLOAD_MODULE
HTTP_UPLOAD_PROGRESS
cd /usr/ports/www/nginx
make config install clean distclean
##### _PHP-FPM_
Compiler _PHP-FPM_ avec les options ci-dessous :
CLI
FPM
SUHOSIN
MULTIBYTE
MAILHEAD
cd /usr/port/lang/php5-extentions
make config install clean distclean
##### Extentions php5
Compiler les extentions _PHP-FPM_ avec les options ci-dessous :
BZ2
CALENDAR
CTYPE
CURL
DOM
FILEINFO
FILTER
GD
HASH
ICONV
JSON
MBSTRING
MCRYPT
OPENSSL
PDF
PHAR
POSIX
SESSION
SIMPLEXML
TOKENIZER
XML
XMLREADER
XMLWRITER
XSL
ZLIB
cd /usr/port/lang/php5-extentions
make config install clean distclean
Et si vous utilisez MySQL, compiler `php5-extentions` avec `MYSQL MYSQLI`.
Il y a aussi des paquets optionnels (ImageMagick est fortement conseillé, GD2 pose des problème avec OpenPhoto).
/usr/ports/net/pecl-oauth
/usr/ports/graphics/ImageMagick-nox11
/usr/ports/graphics/pecl-imagick
/usr/ports/graphics/exiftran
----------------------------------------
### Installer OpenPhoto
Télécharger et installer les sources. Nous vous recommandons d'utiliser le dossier `/usr/local/www/yourdomain.com`.
#### Via git clone
pkg_add -r git-core
git clone git://github.com/photo/frontend.git /usr/local/www/yourdomain.com
#### Via wget/tar
cd /usr/local/www
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf openphoto.tar.gz
mv openphoto-frontend-* yourdomain.com
Assuming that this is a development machine you only need to make the config writable by the user Apache runs as. Most likely `www`.
Vous aurez besoin de créer les dossiers suivant et de leur donner le droit d'ecriture.
mkdir /usr/local/www/yourdomain.com/src/userdata
mkdir /usr/local/www/yourdomain.com/src/html/photos
mkdir /usr/local/www/yourdomain.com/src/html/assets/cache
chown www:www /usr/local/www/yourdomain.com/src/userdata
chown www:www /usr/local/www/yourdomain.com/src/html/photos
chown www:www /usr/local/www/yourdomain.com/src/html/assets/cache
----------------------------------------
### Configuration de Nginx et PHP
#### Nginx
Copier le fichier de configuration proposé dans les sources.
cp /usr/local/www/yourdomain.com/src/configs/openphoto-nginx.conf /usr/local/etc/nginx/sites-enabled/openphoto
Adapter la configuration:
* Votre domaine (openphoto.domain.ltd)
* Le dossier d'installation d'OpenPhoto (/usr/local/www/yourdomain.com/src/html)
/usr/local/etc/nginx/sites-enabled/openphoto
### PHP
Vérifier votre php.ini
vi /usr/local/etc/php.ini
Les variables ci-dessous doivent etre défini de cette maniere.
file_uploads = On
upload_max_filesize = 16M
post_max_size = 16M
Relancer les services, OpenPhoto est maintenant disponible via votre navigateur.
/usr/local/etc/rc.d/php-fpm restart
/usr/local/etc/rc.d/nginx restart
### Ouvrez http://openphoto.domain.ltd dans votre navigateur.
Maintenant vous êtes prêt à lancer votre site OpenPhoto. Acceder a votre site OpenPhoto via votre navigateur sur votre hôte et vous serez redirigé vers un écran de configuration. Vous aurez besoin de vos informations de compte de Cloud pour continuer.
Une fois que vous aurez suivie les 3 étapes OpenPhoto sera en service.
Si pour une raison quelconque vous voulez relancer le _setup_, vous devrez supprimer le fichier de configuration généré et rafraichir votre navigateur.
rm /usr/local/www/yourdomain.com/src/userdata/configs/yourdomain.com.ini
**ENJOY!**

163
docs/guides/InstallationGenericApache.markdown Normal file
View file

@ -0,0 +1,163 @@
OpenPhoto / Installation for Linux - Apache
=======================
#### OpenPhoto, a photo service for the masses
## Generic Installation Guide
This guide is intended to be usable by users of any distribution of Linux running a standard LAMP stack. As such, it is written at a rather high level of abstraction. For distribution-specific details, find a different guide on the sidebar to the left.
### Prerequisites
#### Database Options
Openphoto can use either MySql or Amazon Simpledb to store metadata about photos.
##### MySql
You'll need to provide credentials for a MySql database. If the database doesn't already exist it will be created. If the user doesn't have `CREATE DATABASE` permissions then make sure it's already created.
##### Simpledb
First, make sure you're signed up.
http://aws.amazon.com/simpledb/
After that, pick up an Access Key ID and Secret Access Key from:
https://portal.aws.amazon.com/gp/aws/securityCredentials
#### File System Options
To store photos, openphoto has a number of options.
##### Amazon S3
First, sign up here:
http://aws.amazon.com/s3/
After that, pick up an Access Key ID and Secret Access Key from:
https://portal.aws.amazon.com/gp/aws/securityCredentials
You will also need a bucket name, but this can be anything. Openphoto will create it if necessary.
##### Local Filesystem
Fairly self-explanitory. You must define the folder where you wish to store your photos (Be sure to make this writable by the user Apache runs as!) and the web-accessable hostname which openphoto will use to construct download URLs. This will either be the domain name assigned to the server, or the IP address. Include any necessary subdirectories. Do not include http://.
E.g.:
example.com/photos
127.0.0.1/photos
##### Dropbox
Dropbox is a backup option which can be combined with either S3 or the locl filesystem. To enable it, you need a Key and Secret from:
https://www.dropbox.com/developers/apps
Be sure to allow Full dropbox access. The folder name can be anything, and will be created if necessary.
#### Necessary software
To run openphoto, ensure the following software is installed:
* Apache
* PHP
* Apache PHP module
* PHP Curl module
* PHP mcrypt module
* PHP apc module
* libpcre development libraries and headers
* PHP PEAR
One or more of:
* PHP imagemagick module
* PHP graphicsmagick module
* PHP GD module (not recommended; last resort)
Non-essential but recommended:
* exiftran
* PHP oauth module
* Mysql (if you will be using it)
* PHP pdo mysql module (ditto)
Be sure to modify php.ini to enable each PHP module.
The best place to find PHP modules is your distro's standard repository. If you can't find it packaged there, use `pecl install <package name>`. Find packages at http://pecl.php.net/.
Enable the following Apache modules:
* rewrite
* deflate
* expires
* headers
NOTE: If this is your first time installing Apache on your current distro, be sure to read your distro's documentation on how to set up Apache and how to set up vhosts in Apache. These vary wildly by distro and you are expected to know what to do!
----------------------------------------
### Installing OpenPhoto
Download and install the source code. We recommend the default apache root (Often `/var/www`, or `/srv/http`, check your distro documentation for specifics), but it can go anywhere if Apache's user has permissions to access there.
#### Using git clone
apt-get install git-core
git clone git://github.com/photo/frontend.git <install location>/yourdomain.com
#### Using tar
cd <install location>
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf openphoto.tar.gz
mv openphoto-frontend-* yourdomain.com
Once installed, create these three directories for configuration files:
* yourdomain.com/src/userdata
* yourdomain.com/src/html/photos
* yourdomain.com/src/html/assets/cache
Then chown them all to the user Apache will run as.
----------------------------------------
### Setting up Apache and PHP
#### Apache
You'll need to copy the sample virtual host configuration file from the source to wherever Apache stores virtual host configuration files in your distro. They are stored in:
<install location>/yourdomain.com/src/configs/openphoto-vhost.conf
After copying, edit the file and replace all instances of `/path/to/openphoto/html/directory` with `<install location>/yourdomain.com/src/html`.
It may be necessary to enable openphoto's vhost and disable the default, here. This differs by distro, so check your distro's Apache docs.
By default, any access to ini files is denied with a "Not Found" 404 HTTP code. To enable a 404, or Forbidden return code, change the following lines in the virtual host file.
Uncomment:
# 403 Forbidden for ini files
#RewriteRule \.ini$ - [F,NC]
Comment:
# 404 Not Found for ini files
AliasMatch \.ini$ /404
### PHP
You should also verify that your `php.ini` file has a few important values set correctly.
Find php.ini and open in with a text editor.
Search for the following values and make sure they're correct.
file_uploads = On
upload_max_filesize = 16M
post_max_size = 16M
Now, the site should be ready to use. Start/Restart Apache, and open the host in your browser. You should see a setup screen. You'll need your cloud account credentials to continue.
Once you complete the 3 steps your site will be up and running and you'll be redirected there. The _setup_ screen won't show up anymore, but you can rerun it via the Manage page.
** ENJOY! **

152
docs/guides/InstallationOSXMacports.markdown Normal file
View file

@ -0,0 +1,152 @@
OpenPhoto / Installation for OSX using Macports
=======================
#### OpenPhoto, a photo service for the masses
## OS: Mac OSX
This guide instructs you on how to install OpenPhoto on a Macintosh OSX computer.
----------------------------------------
### Prerequisites
#### Database and File System Options
##### MySql
You'll need to provide credentials for a MySql database. If the database doesn't already exist it will be created. If the user doesn't have `CREATE DATABASE` permissions then make sure it's already created.
##### AWS
If you're going to use AWS services then you'll need to be signed up for them.
* http://aws.amazon.com/simpledb/
* http://aws.amazon.com/s3/
#### Server Packages and Modules
Once you've confirmed that your cloud account is setup you can get started on your server. For that you'll need to have _Apache_, _PHP_ and _curl_ installed with a few modules.
This guide assumes you have Macports installed. If not you can [get it here](http://www.macports.org/install.php). The easiest option is to use `.pkg` installer.
sudo port install apache2
sudo port install php5 +apache2
cd /opt/local/apache2/modules
sudo /opt/local/apache2/bin/apxs -a -e -n "php5" libphp5.so
sudo port install php5-exif
sudo port install php5-curl
sudo port install php5-imagick
sudo port install php5-oauth
sudo port install php5-mcrypt
sudo port install php5-apc
sudo port load apache2
----------------------------------------
### Installing OpenPhoto
Download and install the source code. We recommend `~/Sites/yourdomain.com` but you can use any directory you'd like.
#### Using git clone
# OSX should have git already installed. If not:
sudo port install git-core
git clone git://github.com/photo/frontend.git ~/Sites/yourdomain.com
#### Using tar
cd ~/Sites
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf openphoto.tar.gz
mv openphoto-frontend-* yourdomain.com
Assuming that this is a development machine you can make the config writable by the user Apache runs as. Most likely `_www`.
cd ~/Sites/yourdomain.com
mkdir src/userdata
chown _www src/userdata
----------------------------------------
### Setting up Apache and PHP
#### Apache
You'll need to make sure that you have named virtual hosts enabled in your Apache confs.
sudo nano /opt/local/apache2/conf/httpd.conf
Enable virtual hosts:
# Virtual hosts
Include conf/extra/httpd-vhosts.conf
Ensure the PHP module is loaded (various places in `httpd.conf`):
LoadModule php5_module modules/libphp5.so
DirectoryIndex index.html index.php
Include conf/extra/mod_php.conf
Copy the contents of `~/Sites/yourdomain.com/src/configs/openphoto-vhost.conf` onto your clipboard. Then open your `httpd-vhosts.conf` file.
sudo nano /opt/local/apache2/conf/extra/httpd-vhosts.conf
You can put the `NameVirtualHost` directive at the top of the file.
NameVirtualHost *
Paste the contents of your clipboard into the bottom of the file and replace instances of `/path/to/openphoto/html/directory` with `/Users/yourusername/Sites/yourdomain.com/src/html` or wherever you placed the code. In the virtualhost conf make sure to specify the full path to your `Sites` directory.
By default, any access to ini files is denied with a "Not Found" 404 HTTP code. To enable a 404, or Forbidden return code, change the following lines in the virtual host file.
Uncomment:
# 403 Forbidden for ini files
#RewriteRule \.ini$ - [F,NC]
Comment:
# 404 Not Found for ini files
AliasMatch \.ini$ /404
### PHP
You should also verify that your `php.ini` file has a few important values set correctly.
sudo nano /opt/local/etc/php5/php.ini
If the file is empty, copy the development template file
sudo cp /opt/local/etc/php5/php.ini-development /opt/local/etc/php5/php.ini
Search for the following values and make sure they're correct.
post_max_size = 16M
file_uploads = On
upload_max_filesize = 16M
Now you're ready to restart apache and visit the site in your browser.
sudo /opt/local/apache2/bin/apachectl restart
### Fake domain
If you happen to not have `yourdomain.com` registered, you can fake it by editing your `/etc/hosts` file and adding the following line
127.0.0.1 yourdomain.com
### Launching your OpenPhoto site
Now you're ready to launch your OpenPhoto site. Point your browser to your host and you'll be taken to a setup screen. You'll need your cloud account credentials to continue.
Once you complete the 3 steps your site will be up and running and you'll be redirected there. The setup screen won't show up anymore.
### Performing setup again ###
If for any reason you want to go through the setup again you will need to delete the generated config file and refresh your browser.
rm ~/Sites/yourdomain.com/src/userdata/configs/settings.ini
**ENJOY!**

119
docs/guides/InstallationSUSE.markdown Normal file
View file

@ -0,0 +1,119 @@
OpenPhoto / Installation for SUSE/openSUSE
=======================
#### OpenPhoto, a photo service for the masses
## OS: Linux openSUSE 11.4+
This guide instructs you on how to install OpenPhoto on an openSUSE server.
----------------------------------------
### Prerequisites
#### Database and File System Options
##### MySql
You'll need to provide credentials for a MySql database. If the database doesn't already exist it will be created. If the user doesn't have `CREATE DATABASE` permissions then make sure it's already created.
##### AWS
If you're going to use AWS services then You'll need to be signed up for them.
* http://aws.amazon.com/simpledb/
* http://aws.amazon.com/s3/
#### Server Packages and Modules
Once you've confirmed that your cloud account is setup you can get started on your server. For that you'll need to have _Apache_, _PHP_ and _curl_ installed with a few modules.
zypper in apache2 php5 apache2-mod-php5 php5-curl php5-mcrypt
And if you are going to use MySQL install `php5-mysql`.
Ensure you have mod_rewrite enabled
a2enmod rewrite
There are also a few optional but recommended packages and modules. Add the PHP Extensions repo.
zypper ar http://download.opensuse.org/repositories/server:/php:/extensions/openSUSE_11.4 php:extensions
zypper in php5-imagick php5-oauth php5-APC exiftran
a2enmod deflate
a2enmod expires
a2enmod headers
----------------------------------------
### Installing OpenPhoto
Download and install the source code. We recommend `/srv/www/htdocs/yourdomain.com` but you can use any directory you'd like.
#### Using git clone
zypper in git
git clone https://github.com/photo/frontend.git /srv/www/yourdomain.com
chown -R wwwrun:www /srv/www/htdocs/yourdomain.com
#### Using tar
cd /var/www
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf --group=www --owner=wwwrun openphoto.tar.gz
mv openphoto-frontend-* yourdomain.com
chown -R wwwrun:www yourdomain.com
Assuming that this is a development machine you can make the config writable by the user Apache runs as. Most likely `wwwrun`.
mkdir /srv/www/htsdocs/yourdomain.com/src/userdata
chown wwwrun:www /srv/www/htdocs/yourdomain.com/src/userdata
----------------------------------------
### Setting up Apache and PHP
#### Apache
You'll need to copy the sample virtual host configuration file from the source to `/etc/apache2/vhosts.d`.
cp /srv/www/htdocs/yourdomain.com/src/configs/openphoto-SUSE-vhost.conf /etc/apache2/vhosts.d/yourdomain.com.conf
Now you'll need to replace instances of `/path/to/openphoto/html/directory` with `/srv/www/htdocs/yourdomain.com/src/html` or wherever you placed the code.
vi /etc/apache2/vhosts.d/yourdomain.com.conf
By default, any access to ini files is denied with a "Not Found" 404 HTTP code. To enable a 404, or Forbidden return code, change the following lines in the virtual host file.
Uncomment:
# 403 Forbidden for ini files
#RewriteRule \.ini$ - [F,NC]
Comment:
# 404 Not Found for ini files
AliasMatch \.ini$ /404
### PHP
You should also verify that your `php.ini` file has a few important values set correctly.
vi /etc/php5/apache2/php.ini
Search for the following values and make sure they're correct.
file_uploads = On
upload_max_filesize = 16M
post_max_size = 16M
Now you're ready to restart apache and visit the site in your browser.
rcapache2 restart
### Launching your OpenPhoto site
Now you're ready to launch your OpenPhoto site. Point your browser to your host and you'll be taken to a setup screen. You'll need your cloud account credentials to continue.
Once you complete the 3 steps your site will be up and running and you'll be redirected there. The _setup_ screen won't show up anymore. If for any reason you want to go through the setup again you will need to delete the generated config file and refresh your browser.
rm /srv/www/htdocs/yourdomain.com/src/configs/generated/settings.ini
**ENJOY!**

131
docs/guides/InstallationSharedHosting.markdown Normal file
View file

@ -0,0 +1,131 @@
# OpenPhoto / Installation for Shared Hosting
#### OpenPhoto, a photo service for the masses
## Installation on Shared Hosting
This guide instructs you on how to install OpenPhoto on shared hosting sites such as Dreamhost or Bluehost. OpenPhoto can be difficult to install for users not experienced with performing such installations. If you'd like to use OpenPhoto without installing the software yourself, <a href="http://openphoto.me">get started here</a>.
If you're using Dreamhost <a href="https://github.com/photo/frontend/blob/master/documentation/guides/InstallationDreamhost.markdown">we have a community-written guide for Dreamhost users</a>. Because every webhost is unique, we welcome additions to this guide as well as guides on installing OpenPhoto on your webhost.
*OpenPhoto should be installed in the root directory of a domain or subdomain.*
Variables:
- *OpenPhotoRoot*: the root directory for OpenPhoto (e.g., ~/openphoto)
### Before you install OpenPhoto
This guide assumes you have:
* Checked that your webhost supports MySQL and PHP
* Shell or FTP access to your web server
* An FTP or SSH client
* A web browser of choice
* An external cloud service account on Amazon or Dropbox (if you want to store your photos there)
### The short version
Here's the short version of the instructions for those already comfortable with installing software on a web server. You can check out the detailed instructions below for more information on each step.
1. Download the latest version of OpenPhoto from Github and extract it to the root folder of your website. <a href="https://github.com/photo/frontend/archive/master.zip">Direct link to latest version as a .zip file</a>
2. Prepare your cloud storage option and have your credentials ready. (Optional)
3. Create a new MySQL database and a new user for that database. Remember the hostname (the default should be fine), database name, username, and password. Your webhost may have a MySQL control panel such as PhpMyAdmin that you can do this in.
4. Create the following folders and chmod them to 775:
mkdir OpenPhotoRoot/src/html/assets/cache
chmod 775 OpenPhotoRoot/src/html/assets/cache
mkdir OpenPhotoRoot/src/html/photos
chmod 775 OpenPhotoRoot/src/html/photos
mkdir OpenPhotoRoot/src/userdata
chmod 775 OpenPhotoRoot/src/userdata
5. Visit your website and follow the instructions.
That's it! OpenPhoto should now be installed. Because there are so many special cases specific to individual webhosts along with things that could go wrong, you may want to read the full instructions below.
### The detailed version
#### 1. Download OpenPhoto from Github.
<a href="https://github.com/photo/frontend/archive/master.zip">Direct link to latest version as a .zip file</a>. You can also do the following:
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf openphoto.tar.gz
mv openphoto-frontend-* OpenPhotoRoot
#### 2. Install any dependencies or modules needed.
Your webhost may include them by default. Check their documentation. Here's what you'll need:
* The Pecl extension oauth for authentication
* ImageMagick or GD for photo rendering
The method of installing these varies by webhost. Some webhosts let you install them by yourself; others will install these for you if you contact them.
#### 3. Create your cloud accounts (optional).
Create an account at <a href="https://aws.amazon.com/s3">Amazon AWS</a> or <a href="http://www.dropbox.com">Dropbox</a> if you plan to use them. Create a new bucket (S3) or app (Dropbox). Save your keys since you'll need them soon.
At Amazon:
* Sign in and visit <a href="https://console.aws.amazon.com/s3/home">the S3 panel</a> and select Create a New Bucket.
* Give your bucket a name and select a region, then select Create.
* <a href="https://portal.aws.amazon.com/gp/aws/securityCredentials">Obtain your access keys</a> and save them.
At Dropbox:
* Sign in and create a folder for your photos to go in.
* Visit <a href="https://www.dropbox.com/developers/apps">the developers page</a>
* Select Create an App, and select Core API for App Type and Full Dropbox Access.
This will give you a development app to use for your photos. Save your access keys; you'll need them soon.
#### 4. Create a database and user.
Visit your control panel for managing databases and create a new database and new user for the database. Give the user `CREATE DATABASE` privileges. Remember the hostname (the default should be fine), database name, username, and password. You'll need these during setup.
#### 5. Configure the subdomain or domain.
You may have to add the domain if you're bringing in a new domain. Consult your webhost's documentation if needed. Depending on your webhost you may have to visit multiple areas of the site to configure everything, or you may have to configure these separately. But here's what you need to set up.
* PHP: Select the latest version, FastCGI configuration if available
* Web directory: OpenPhotoRoot/src/html
#### 6. Upload OpenPhoto.
Upload the contents of the downloaded OpenPhoto folder to OpenPhotoRoot if you haven't already done that. You can do this with an FTP or SSH client.
#### 7. Create the following directories.
the cache:
mkdir OpenPhotoRoot/src/html/assets/cache
chmod 775 OpenPhotoRoot/src/html/assets/cache
to store your photos if you're planning on local storage:
mkdir OpenPhotoRoot/src/html/photos
chmod 775 OpenPhotoRoot/src/html/photos
to store userdata:
mkdir OpenPhotoRoot/src/userdata
chmod 775 OpenPhotoRoot/src/userdata
#### 8. Install OpenPhoto
After waiting a sufficient amount of time for the subdomain name to propagate, use the browser to connect to the new subdomain. You should see a setup page for OpenPhoto which will allow you to configure your OpenPhoto project.
* Enter your email address and select a password.
* Select your image renderer (ImageMagick or GD are the most common options), database (MySQL or InnoDB), and storage (Local filesystem, Amazon S3, Amazon S3+Dropbox, Local filesystem+Dropbox).
* Enter your credentials for your database, Amazon S3, or Dropbox.
**ENJOY!**
### Troubleshooting
#### Setup page looks strange (black and white, unstyled)
If the setup page is not colorful and well formatted, then the css and javascript files are most likely not being loaded. Possible causes:
- Web directory root is not properly set (check control panel for the subdomain)
- src/html/assets/cache directory is not writeable by Apache (check your permissions)
#### My webhost doesn't recognize OpenPhotoRoot/src/html as the index directory.
You can set this in the .htaccess page at OpenPhotoRoot/src. If your webhost lets you set this through the web panel you can also do that there.
#### Error setting up the database
Double check all the parameters. Check your database control panel and verify that everything is correct. Also double check that the user for your database has permission to create a database.

130
docs/guides/InstallationUbuntuApache.markdown Normal file
View file

@ -0,0 +1,130 @@
OpenPhoto / Installation for Ubuntu + Apache
=======================
#### OpenPhoto, a photo service for the masses
## OS: Linux Ubuntu Server 10.04+
This guide instructs you on how to install OpenPhoto on an Ubuntu Server.
----------------------------------------
### Prerequisites
#### Database and File System Options
##### MySql
You'll need to provide credentials for a MySql database. If the database doesn't already exist it will be created. If the user doesn't have `CREATE DATABASE` permissions then make sure it's already created.
##### AWS
If you're going to use AWS services then You'll need to be signed up for them.
* http://aws.amazon.com/simpledb/
* http://aws.amazon.com/s3/
#### Server Packages and Modules
Once you've confirmed that your cloud account is setup you can get started on your server. For that you'll need to have _Apache_, _PHP_ and _curl_ installed with a few modules.
apt-get update
apt-get upgrade
apt-get install apache2 php5 libapache2-mod-php5 php5-curl php5-gd php5-mcrypt php-apc build-essential libpcre3-dev php-pear
a2enmod rewrite
And if you are going to use MySQL install `php5-mysql`.
There are also a few optional but recommended packages and modules.
apt-get install php5-dev php5-imagick exiftran
pecl install oauth
a2enmod deflate
a2enmod expires
a2enmod headers
----------------------------------------
### Installing OpenPhoto
Download and install the source code. We recommend `/var/www/yourdomain.com` but you can use any directory you'd like.
#### Using git clone
apt-get install git-core
git clone git://github.com/photo/frontend.git /var/www/yourdomain.com
#### Using tar
cd /var/www
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf openphoto.tar.gz
mv openphoto-frontend-* yourdomain.com
Assuming that this is a development machine you only need to make the config writable by the user Apache runs as. Most likely `www-data`.
mkdir /var/www/yourdomain.com/src/userdata
mkdir /var/www/yourdomain.com/src/html/photos
mkdir /var/www/yourdomain.com/src/html/assets/cache
chown www-data:www-data /var/www/yourdomain.com/src/userdata
chown www-data:www-data /var/www/yourdomain.com/src/html/photos
chown www-data:www-data /var/www/yourdomain.com/src/html/assets/cache
----------------------------------------
### Setting up Apache and PHP
#### Apache
You'll need to copy the sample virtual host configuration file from the source to `/etc/apache2/sites-available`.
cp /var/www/yourdomain.com/src/configs/openphoto-vhost.conf /etc/apache2/sites-available/openphoto
You'll need to replace instances of `/path/to/openphoto/html/directory` with `/var/www/yourdomain.com/src/html` or wherever you placed the code. Depending on which modules you installed you may have to comment out some of the `Expires*` directives.
vi /etc/apache2/sites-available/openphoto
Now enable openphoto and disable Apache's default virtual host.
a2dissite default
a2ensite openphoto
By default, any access to ini files is denied with a "Not Found" 404 HTTP code. To enable a 403, or Forbidden return code, change the following lines in the virtual host file.
Uncomment:
# 403 Forbidden for ini files
#RewriteRule \.ini$ - [F,NC]
Comment:
# 404 Not Found for ini files
AliasMatch \.ini$ /404
### PHP
You should also verify that your `php.ini` file has a few important values set correctly.
vi /etc/php5/apache2/php.ini
Search for the following values and make sure they're correct.
file_uploads = On
upload_max_filesize = 16M
post_max_size = 16M
Search for, and if needed add the following line to load the Oauth Extention.
extension=oauth.so
Now you're ready to restart apache and visit the site in your browser.
/etc/init.d/apache2 restart
### Launching your OpenPhoto site
Now you're ready to launch your OpenPhoto site. Point your browser to your host and you'll be taken to a setup screen. You'll need your cloud account credentials to continue.
Once you complete the 3 steps your site will be up and running and you'll be redirected there. The _setup_ screen won't show up anymore. If for any reason you want to go through the setup again you will need to delete the generated config file and refresh your browser.
rm /var/www/yourdomain.com/src/userdata/configs/yourdomain.com.ini
**ENJOY!**

167
docs/guides/InstallationUbuntuApache.sh Executable file
View file

@ -0,0 +1,167 @@
#!/bin/bash
#######################################
# OpenPhoto Install
# Run with sudo for best results
#######################################
SECONDS=0
if [[ "$(/usr/bin/whoami)" != "root" ]]; then
echo "This script must be run as root or using sudo.Script aborted."
exit 1
fi
echo ""
echo ""
echo "===================================================="
echo "Updating Ubuntu and apt-get"
echo "===================================================="
echo ""
echo ""
apt-get update --assume-yes --quiet
apt-get upgrade --assume-yes --quiet
echo ""
echo ""
echo "===================================================="
echo "Installing needed packages and modules"
echo "===================================================="
echo ""
echo ""
apt-get install --assume-yes --quiet apache2 mysql-server mysql-client php5 libapache2-mod-php5 php5-curl curl php5-gd php5-mcrypt php5-mysql php-pear php-apc build-essential libpcre3-dev
a2enmod rewrite
echo ""
echo ""
echo "===================================================="
echo "Installing optional but recommended packages and modules"
echo "===================================================="
echo ""
echo ""
apt-get install --assume-yes --quiet php5-dev php5-imagick exiftran
a2enmod deflate
a2enmod expires
a2enmod headers
echo ""
echo ""
echo "===================================================="
echo "Installing oauth from pecl"
echo "===================================================="
echo ""
echo ""
pecl install oauth
mkdir -p /etc/php5/apache2/conf.d/
echo "extension=oauth.so" >> /etc/php5/apache2/conf.d/oauth.ini
echo ""
echo ""
echo "===================================================="
echo "Downloading OpenPhoto and unpacking"
echo "===================================================="
echo ""
echo ""
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf openphoto.tar.gz > /dev/null 2>&1
mv photo-frontend-* /var/www/openphoto
sudo rm openphoto.tar.gz
echo ""
echo ""
echo "===================================================="
echo "Setting permissions for Dev server"
echo "===================================================="
echo ""
echo ""
mkdir /var/www/openphoto/src/userdata
chown www-data:www-data /var/www/openphoto/src/userdata
mkdir /var/www/openphoto/src/html/assets/cache
chown www-data:www-data /var/www/openphoto/src/html/assets/cache
mkdir /var/www/openphoto/src/html/photos
chown www-data:www-data /var/www/openphoto/src/html/photos
echo ""
echo ""
echo "===================================================="
echo "Setting up Apache"
echo "===================================================="
echo ""
echo ""
cp /var/www/openphoto/src/configs/openphoto-vhost.conf /etc/apache2/sites-available/openphoto
sed 's/\/path\/to\/openphoto\/html\/directory/\/var\/www\/openphoto\/src\/html/g' /var/www/openphoto/src/configs/openphoto-vhost.conf > /etc/apache2/sites-available/openphoto
a2dissite default
a2ensite openphoto
echo ""
echo ""
echo "===================================================="
echo "Adjusting PHP settings"
echo "===================================================="
echo ""
echo ""
sed -e 's/file_uploads.*/file_uploads = On/g' -e 's/upload_max_filesize.*/upload_max_filesize = 16M/g' -e 's/post_max_size.*/post_max_size = 16M/g' /etc/php5/apache2/php.ini > /etc/php5/apache2/php.ini.tmp
mv /etc/php5/apache2/php.ini.tmp /etc/php5/apache2/php.ini
echo ""
echo ""
echo "===================================================="
echo "Launching Your OpenPhoto site"
echo "===================================================="
echo ""
echo ""
/etc/init.d/apache2 restart
# finding IP address and compensating for possible EC2 installation
EC2=`curl --silent --connect-timeout 1 http://169.254.169.254/latest/meta-data/public-hostname`
if [[ $EC2 != "" ]];
then
IP=`echo $EC2 | sed -rn 's/ec2-(.*?)\.compute.*/\1/p' | sed 's/-/./g'`
else
IP=`ifconfig eth0 | grep 'inet addr:' | cut -d: -f2 | awk '{ print $1}'`
fi
echo ""
echo ""
echo ""
echo "****************************************************"
echo "===================================================="
echo "CONGRATULATIONS!!!"
echo ""
echo "The photographic heavens are applauding your"
echo "brand new installation of OpenPhoto."
echo ""
echo ""
echo "Took $SECONDS seconds to install."
echo ""
echo ""
echo "Now you can test your installation by directing your"
echo "browser to $IP"
echo "===================================================="
echo "****************************************************"
echo ""
echo ""
echo ""
echo ""
echo ""
echo ""

132
docs/guides/InstallationUbuntuCherokee.markdown Normal file
View file

@ -0,0 +1,132 @@
OpenPhoto / Installation for Ubuntu + Cherokee
=======================
#### OpenPhoto, a photo service for the masses
## OS: Linux Ubuntu Server 10.04+
This guide instructs you on how to install OpenPhoto on Cherokee Web Server on an Ubuntu server.
To have a recent version of Cherokee, I advice to add the ppa maintained with latest version. You can add it with the command below.
add-apt-repository ppa:cherokee-webserver/ppa
----------------------------------------
### Prerequisites
#### Database and File System Options
##### MySql
You'll need to provide credentials for a MySql database. If the database doesn't already exist it will be created. If the user doesn't have `CREATE DATABASE` permissions then make sure it's already created.
##### AWS
If you're going to use AWS services then You'll need to be signed up for them.
* http://aws.amazon.com/simpledb/
* http://aws.amazon.com/s3/
#### Server Packages and Modules
Once you've confirmed that your cloud account is setup you can get started on your server. For that you'll need to have _Cherokee_, _PHP_ and _curl_ installed with a few modules.
apt-get update
apt-get upgrade
apt-get install cherokee php5-fpm php5-curl php5-mcrypt php-apc build-essential libpcre3-dev
And if you are going to use MySQL install `php5-mysql`.
There are also a few optional but recommended packages and modules.
apt-get install php5-imagick exiftran
pecl install oauth
----------------------------------------
### Installing OpenPhoto
Download and install the source code. We recommend `/var/www/yourdomain.com` but you can use any directory you'd like.
#### Using git clone
apt-get install git-core
git clone git://github.com/photo/frontend.git /var/www/yourdomain.com
chown -R www-data:www-data /var/www/yourdomain.com
#### Using tar
cd /var/www
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf openphoto.tar.gz
mv openphoto-frontend-* yourdomain.com
chown -R www-data:www-data yourdomain.com
Assuming that this is a development machine you can make the config writable by the user Apache runs as. Most likely `www-data`.
mkdir /var/www/yourdomain.com/src/userdata
chown www-data:www-data /var/www/yourdomain.com/src/userdata
----------------------------------------
### Setting up Cherokee and PHP
### PHP
You should also verify that your `php.ini` file has a few important values set correctly.
vi /etc/php5/fpm/php.ini
Search for the following values and make sure they're correct.
file_uploads = On
upload_max_filesize = 16M
post_max_size = 16M
Now you're ready to restart php5-fpm to use the new parameters.
/etc/init.d/php5-fpm restart
### Cherokee
Launch the administration web interface and connect to it
cherokee-admin
firefox http://localhost:9090
Note that if you're not connecting from the same machine, you'll have to use the `-b[<IP>]` parameter to bind cherokee-admin to an externally accessible network interface.
Go the sections "Vservers" and create a new vserver with the + button
In the "Languages" sub-section, choose "PHP" and click "Add"
Set the Document Root to `/var/www/yourdomain.com/src/html` and click "Next"
Enter the Vhost Name the configuration will serve and set the log configuration; click "Create"
Now, go to the rules definition and add a "File Exists" rules, invert the rule with "Not" button and set the following parameters:
* Match any file: enable
* Use I/O Cache: enable
* Only match files: disable
* If dir, check Index files: disable
Go to the tab "Handler", set a "Redirection" handler with the following parameters:
* Show: Internal
* Regular Expression: `^/([^?]*)(\?+([^?]*))*$`
* Substitution: `index.php?__route__=/$1&$3`
Click "Add".
Press the button "Save", and restart Cherokee.
### Launching your OpenPhoto site
Now you're ready to launch your OpenPhoto site. Point your browser to your host and you'll be taken to a setup screen. You'll need your cloud account credentials to continue.
Once you complete the 3 steps your site will be up and running and you'll be redirected there. The _setup_ screen won't show up anymore. If for any reason you want to go through the setup again you will need to delete the generated config file and refresh your browser.
rm /var/www/yourdomain.com/src/configs/generated/settings.ini
FIXME: On some systems (?), this config file is in another spot:
/var/www/yourdomain.com/src/userdata/configs/yourdomain.com.ini
**ENJOY!**

112
docs/guides/InstallationUbuntuLighttpd.markdown Normal file
View file

@ -0,0 +1,112 @@
OpenPhoto / Installation for Lighttpd on Ubuntu/Debian
=======================
#### OpenPhoto, a photo service for the masses
This guide instructs you on how to install OpenPhoto under Lighttpd on Ubuntu or Debian
----------------------------------------
### Prerequisites
#### Database and File System Options
##### MySql
You'll need to provide credentials for a MySql database. If the database doesn't already exist it will be created. If the user doesn't have `CREATE DATABASE` permissions then make sure it's already created.
##### AWS
If you're going to use AWS services then You'll need to be signed up for them.
* http://aws.amazon.com/simpledb/
* http://aws.amazon.com/s3/
#### Server Packages and Modules
Once you've confirmed that your database is setup you can get started on your server. For that you'll need to have _Lighttpd_, and _PHP_ installed with a few modules.
apt-get update
apt-get upgrade
apt-get install lighttpd php5-cgi php5-curl php5-gd php5-mcrypt php-apc
And if you are going to use MySQL install `php5-mysql`.
There are also a few optional but recommended packages and modules.
apt-get install php5-imagick exiftran
----------------------------------------
### Installing OpenPhoto
Download and install the source code. We recommend `/var/www/yourdomain.com` but you can use any directory you'd like.
#### Using git clone
apt-get install git-core
git clone git://github.com/photo/frontend.git /var/www/yourdomain.com
#### Using tar
cd /var/www
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf openphoto.tar.gz
mv openphoto-frontend-* yourdomain.com
There are certain directories that need to be created and made writable by the user the Lighttpd server runs as. Most likely (on Ubuntu/Debian) this is `www-data`.
mkdir /var/www/yourdomain.com/src/userdata
mkdir /var/www/yourdomain.com/src/html/photos
mkdir /var/www/yourdomain.com/src/html/assets/cache
chown www-data:www-data /var/www/yourdomain.com/src/userdata
chown www-data:www-data /var/www/yourdomain.com/src/html/photos
chown www-data:www-data /var/www/yourdomain.com/src/html/assets/cache
----------------------------------------
### Setting up Lighttpd and PHP
#### Lighttpd
First you will need to copy the sample Lighttpd configuration into a place where Lighty can find it.
cp /var/www/yourdomain.com/src/configs/openphoto-lighttpd.conf /etc/lighttpd/conf-available/99-openphoto.conf
The `99` in the prefix of the destination filename above is so that Lighttpd loads our OpenPhoto configuration last. In reality you can use any number greater than the prefix of the FastCGI configuration.
Next open the configuration you just copied and edit it to match your site. Edit the `$HTTP["host"]` line and replace the variable contents with the subdomain where you are installing OpenPhoto. The value is a regular expression, so keep the `\.` which matches a period instead of any character as well as the `^` `$` to direct matching the beginning and end of the hostname respectively.
Now replace the path on the `server.document-root` line with the path to the `src/html` sub-directory where you downloaded/copied OpenPhoto. This path would be `/var/www/yourdomain.com/src/html` if you followed the directions in the last section exactly.
A few modules must be enabled for use by Lighty for our OpenPhoto install. First edit `/etc/lighttpd/lighttpd.conf` and uncomment the line for `mod_rewrite` under the `server.modules` section. Next enable PHP through the FastCGI module from the command line.
lighttpd-enable-mod fastcgi
Finally, enable your edited configuration and force Lighty to reload its configuration.
lighttpd-enable-mod openphoto
/etc/init.d/lighttpd force-reload
### PHP
You should also verify that your `php.ini` file has a few important values set correctly.
vi /etc/php5/cgi/php.ini
Search for the following values and make sure they're correct.
file_uploads = On
upload_max_filesize = 16M
post_max_size = 16M
If you made any changes then restart your Lighttpd server.
/etc/init.d/lighttpd restart
### Launching your OpenPhoto site
Now you're ready to launch your OpenPhoto site. Point your browser to your host and you'll be taken to a setup screen. You'll need your cloud account credentials to continue.
Once you complete the 3 steps your site will be up and running and you'll be redirected there. The _setup_ screen won't show up anymore. If for any reason you want to go through the setup again you will need to delete the generated config file and refresh your browser.
rm /var/www/yourdomain.com/src/userdata/configs/yourdomain.com.ini
**ENJOY!**

115
docs/guides/InstallationUbuntuNGinx.markdown Normal file
View file

@ -0,0 +1,115 @@
OpenPhoto / Installation for Ubuntu|Debian + Nginx
=======================
#### OpenPhoto, a photo service for the masses
## OS: Linux Ubuntu 12.04+ or Debian 6.0+
This guide instructs you on how to install OpenPhoto on an Ubuntu Desktop|Server or Debian distribution.
----------------------------------------
### Prerequisites
#### Database and File System Options
##### MySql
You'll need to provide credentials for a MySql database. If the database doesn't already exist it will be created. If the user doesn't have `CREATE DATABASE` permissions then make sure it's already created.
##### AWS
If you're going to use AWS services then You'll need to be signed up for them.
* http://aws.amazon.com/simpledb/
* http://aws.amazon.com/s3/
#### Server Packages and Modules
Once you've confirmed that your cloud account is setup you can get started on your server. For that you'll need to have _NGinx_, _PHP-FPM_ and _CURL_ installed with a few modules.
apt-get update
apt-get upgrade
apt-get install nginx php5-fpm curl php5-curl php5-gd php5-mcrypt php-pear
And if you are going to use MySQL install `php5-mysql`.
There are also a few optional but recommended packages and modules.
apt-get install php5-dev php5-imagick exiftran
pecl install oauth
sh -c "echo \"extension=oauth.so\" >> /etc/php5/conf.d/oauth.ini"
----------------------------------------
### Installing OpenPhoto
Download and install the source code. We recommend `/var/www/yourdomain.com` but you can use any directory you'd like.
#### Using git clone
apt-get install git-core
git clone git://github.com/photo/frontend.git /var/www/yourdomain.com
#### Using tar
cd /var/www
wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
tar -zxvf openphoto.tar.gz
mv openphoto-frontend-* yourdomain.com
Assuming that this is a development machine you only need to make the config writable by the user Nginx runs as. Most likely `www-data`.
mkdir /var/www/yourdomain.com/src/userdata
mkdir /var/www/yourdomain.com/src/html/photos
mkdir /var/www/yourdomain.com/src/html/assets/cache
chown www-data:www-data /var/www/yourdomain.com/src/userdata
chown www-data:www-data /var/www/yourdomain.com/src/html/photos
chown www-data:www-data /var/www/yourdomain.com/src/html/assets/cache
----------------------------------------
### Setting up NGinx and PHP
#### NGinx
You'll need to copy the sample virtual host configuration file from the source to `/etc/nginx/sites-enabled`.
cp /var/www/yourdomain.com/src/configs/openphoto-nginx.conf /etc/nginx/sites-enabled/openphoto
You'll need to replace:
* The host name (yourdomain.com)
* The path where OpenPhoto is installed (/var/www/yourdomain.com/src/html/)
`/etc/nginx/sites-enabled/openphoto`
You also need to change the port on which nginx talks to PHP. Change the
comments in the fastcgi_pass section to look like this:
#fastcgi_pass 127.0.0.1:9000;
# Unix socket is faster and default on Ubuntu/Debian:
fastcgi_pass fastcgi_pass unix:/var/run/php5-fpm.sock;
### PHP
You should also verify that your `php.ini` file has a few important values set correctly.
vi etc/php5/fpm/php.ini
Search for the following values and make sure they're correct.
file_uploads = On
upload_max_filesize = 16M
post_max_size = 16M
Now you're ready to restart apache and visit the site in your browser.
service php-fpm restart
service nginx restart
### Launching your OpenPhoto site
Now you're ready to launch your OpenPhoto site. Point your browser to your host and you'll be taken to a setup screen. You'll need your cloud account credentials to continue.
Once you complete the 3 steps your site will be up and running and you'll be redirected there. The _setup_ screen won't show up anymore. If for any reason you want to go through the setup again you will need to delete the generated config file and refresh your browser.
rm /var/www/yourdomain.com/src/userdata/configs/yourdomain.com.ini
**ENJOY!**

56
docs/guides/InstallationUsingOpenPhotoEC2-AMI.markdown Normal file
View file

@ -0,0 +1,56 @@
OpenPhoto / Installation for AWS EC2 using an AMI
=======================
#### OpenPhoto, a photo service for the masses
### Prerequisites
#### Cloud Accounts
Before setting up your server you'll need to make sure you have your cloud accounts set up. If you're using Amazon then make sure you've enabled both S3 and SimpleDb.
* http://aws.amazon.com/simpledb/
* http://aws.amazon.com/s3/
### Starting up an OpenPhoto EC2 Instance
1. Sign Into AWS Management Console and make sure "Amazon Elastic Compute Cloud (EC2)" is selected from the dropdown menu.
1. Click AMIs under Images.
1. Search for openphoto-instance.
1. Select the latest version by date or version.
1. Click Launch.
1. Click through EC2 options.
1. Ensure selected security group allow HTTP & SSH access.
1. Click back to Instances and wait for new instance to finish starting.
1. Once started, click on the new instance in the web interface, copy the public DNS information.
### Launching your OpenPhoto site
Now you're ready to launch your OpenPhoto site. Point your browser to your new EC2 host and you'll be taken to a setup screen. You'll need your cloud account credentiato continue.
Once you complete the 3 steps your site will be up and running and you'll be redirected there. The _setup_ screen won't show up anymore. If for any reason you want to go through the setup again you will need to delete the generated config file and refresh your browser.
rm /var/www/yourdomain.com/src/configs/generated/settings.ini
**ENJOY!**
### TroubleShooting
#### Can't write to config directory
Open a terminal or SSH client, using your amazon ec2 ssh public key, ssh into the instance as the ubuntu user using the public DNS information for your instance.
ssh -i amazon-key.pem ubuntu@new-instance.amazonaws.com
Verify the apache user has write access to the /home/ubuntu/openphoto/src/configs directory.
cd /home/ubuntu/openphoto/src/
ls -ld ./configs
drwxr-xr-x 3 www-data www-data 4096 2011-08-20 02:37 configs

20
docs/hooks/pre-commit Executable file
View file

@ -0,0 +1,20 @@
#!/usr/bin/php
<?php
/*
* Git pre-commit hook
* To use this just symlink it to .git/hooks/pre-commit or copy it there and make modifications as needed.
*/
$baseDir = sprintf('%s/src/tests', dirname(dirname(dirname(__FILE__))));
chdir($baseDir);
printf("%sGit pre-commit hook %1\$s", PHP_EOL);
$projectName = basename(getcwd());
exec('phpunit --configuration phpunit.xml ./', $output, $returnCode); // Assuming cwd here
if ($returnCode !== 0) {
$minimalTestSummary = array_pop($output);
printf("Test suite for %s failed: ", $projectName);
echo implode("\n", $output);
printf("( %s ) %s%2\$s", $minimalTestSummary, PHP_EOL);
exit(1);
}
printf("All tests for %s passed.%s%2\$s", $projectName, PHP_EOL);
exit(0);

54
docs/schemas/Action.markdown Normal file
View file

@ -0,0 +1,54 @@
Schema for a Action object
=======================
----------------------------------------
### What's an Action object for?
The Social object stores social actions taken on a user's [Photo][Photo].
This includes comments and favorites and could include other social actions in the future.
----------------------------------------
### Schema for a Action object
{
id: (string),
appId: (string),
targetId: (string), // FK Photos.id or Social.id
targetType: (string), // photo, social
email: (string),
name: (string),
avatar: (string),
website: (string),
targetUrl: (string), // link to the target which this row is a child of
permalink: (string), // link to this social element (comment, favorite)
type: (string), // comment, favorite
value: (string),
datePosted: (string),
status: (int)
}
----------------------------------------
### Schema description
* id, base 36 value of a base 10 auto-incremented value
* appId, A string identifing the application creating this entry
* targetId, a foreign key to a [Photo][Photo] or [Action][Action] object this action was taken on
* targetType, a reference to the target type: photo or social
* email, email address of the user taking this action
* name, name of the user taking this action
* avatar, URL to an image which represents this user's avatar or profile photo
* website, URL to the user's website
* targetUrl, URL to the [Photo][Photo] referenced by photoId in this entry
* permalink, URL to this action
* type, Enumeration determining the type of action - comment or favorite
* value, Content of the action such as the text of a comment
* datePosted, UNIX timestamp of the action
* status, Binary value if the action is active or not
[User]: http://theopenphotoproject.org/documentation/schemas/User
[Photo]: http://theopenphotoproject.org/documentation/schemas/Photo
[Action]: http://theopenphotoproject.org/documentation/schemas/Action

42
docs/schemas/Credential.markdown Normal file
View file

@ -0,0 +1,42 @@
Schema for a Credential object
=======================
----------------------------------------
### What's a Credential object for?
The Credential object stores permissioning OAuth tokens granted by the user to various applications.
Due to the distrubuted nature of the platform the model for applications and users is flattened and not relational. For every application there will be exactly 1 user.
----------------------------------------
### Schema for a User object
{
id: (string),
name: (string),
image: (string),
clientSecret: (string),
userToken: (string),
userSecret: (string),
permissions: (set),
verifier: (string),
type: (enum),
status: (bool)
}
----------------------------------------
### Schema description
* id, A (quasi-)public token which identifies the application
* name, A human readable name describing the client
* image, The base64 encoded version of a 100x100 pixel image
* clientSecret, A shared secret used to verify requests originated from the application
* userToken, A (quasi-)public token which idenfies the user
* userSecret, A shared secret to verify that the request originated from the application for the user
* permissions, A set of permissions the credential has (create, read, write, delete)
* verifier, A verification string to ensure that the `oauth_callback` parameter wasn't spoofed
* type, An enumerated field specifying the type of token (unauthorized_request, request, access)
* status, Numeric representation of the status (0=deleted, 1=active)

33
docs/schemas/Group.markdown Normal file
View file

@ -0,0 +1,33 @@
Schema for a Group object
=======================
----------------------------------------
### What's a Group object for?
The Group object stores information for a given group.
A Group consists of an `id`, `name` and array of `email addresses`.
----------------------------------------
### Schema for a Group object
{
id: (string),
appId: (string),
name: (string),
members: (set)
}
----------------------------------------
### Schema description
* id, a string idenfier
* appId, the appId which created this group
* name, the name of the group
* members: a set of email addresses who belong to this group
[User]: http://theopenphotoproject.org/documentation/schemas/User
[Photo]: http://theopenphotoproject.org/documentation/schemas/Photo
[Action]: http://theopenphotoproject.org/documentation/schemas/Action

111
docs/schemas/Photo.markdown Normal file
View file

@ -0,0 +1,111 @@
Schema for a Photo object
=======================
----------------------------------------
### What's a Photo object for?
The Photo object represents a single photo in a user's photo collection.
This includes EXIF information from the photo, tags and URLs to all versions of the photo.
----------------------------------------
### Schema for a Photo object
{
id: (string),
appId: (string),
url: (string),
host: (string),
title: (string),
description: (string),
key: (string),
hash: (string),
tags: (set),
size: (int), // in kb
width: (int),
height: (int),
rotation: (int),
exifOrientation: (int), // degrees
exifCameraMake: (string),
exifCameraModel: (string),
exifExpsureTime: (string),
exifFNumber: (string),
exifMaxApertureValue: (string),
exifMeteringMode: (string),
exifFlash: (string),
exifFocalLength: (string),
altitude: (int),
latitude: (float),
longitude: (float),
views: (int),
status: (int), // binary
permission: (int), // binary
groups: (set),
license: (string),
dateTaken: (int), // unix timestamp
dateTakenDay: (int)
dateTakenMonth: (int)
dateTakenYear: (int)
dateUploaded: (int), // unix timestamp
dateUploadedDay: (int)
dateUploadedMonth: (int)
dateUploadedYear: (int)
pathOriginal: (string),
pathBase: (string),
...
pathWxH: (string), // pseudo key
// path400x300: (string)
// path250x250: (string)
// path800x600: (string)
}
----------------------------------------
### Scema description
* id, Base 36 value of a base 10 auto-incremented value
* appId, A string identifing the application creating this entry
* url, Url to view this photo on the user's OpenPhoto site
* host, Host on which this photo resides
* title, A title for the photo up to 100 chars
* description, A description for the photo up to 255 chars
* key, A random sha1 hash
* hash, The sha1 hash of the original photo
* tags, A set of tags which is searchable inclusive or exclusively
* size, Size of the photo rounded to the nearest Kilobyte
* width, Width of the photo in pixels
* height, Height of the photo in pixels
* rotation, Degress the user has rotated the photo (0, 90, 180, 270)
* exifOrientation, Rotation of the camera in degrees
* exifCameraMake, Camera make, i.e. Canon
* exifCcameraModel, Camera model, i.e. EOS Rebel
* exifExpsureTime
* exifFNumber, F Number i.e f/4.0
* exifMaxApertureValue
* exifMeteringMode
* exifFlash, Indication if the flash fired
* exifFocalLength
* gpsAltitude
* gpsLatitude
* gpsLongitude
* views, Number of times the photo was viewed (excludes views by the owner)
* status, Numeric representation of the status (0=deleted, 1=active)
* permission, binary representation of photo permission (0=not public, 1=public)
* groups, A set of group IDs which whitelist email addresses for permissions to this photo
* license, Abbreviation of the CC licenses such as BY, BY-SA, BY-ND, _blank_ (All rights reserved) or free form (http://creativecommons.org/licenses/)
* dateTaken, Unix timestamp of when the photo was taken
* dateTakenDay, Day the photo was taken (for searching)
* dateTakenMonth, Month the photo was taken (for searching)
* dateTakenYear, Year the photo was taken (for searching)
* dateUploaded, Unix timestamp of when the photo was uploaded
* dateUploadedDay, Day the photo was uploaded (for searching)
* dateUploadedMonth, Month the photo was uploaded (for searching)
* dateUploadedYear, Year the photo was uploaded (for searching)
* pathOriginal, The URL of the original photo
* pathBase, The URL of the base version of the photo, used for photo generation
* pathWxH, A pseudo key which represents any resized version of a photo and it's URL
[User]: http://theopenphotoproject.org/documentation/schemas/User
[Photo]: http://theopenphotoproject.org/documentation/schemas/Photo
[Action]: http://theopenphotoproject.org/documentation/schemas/Action

37
docs/schemas/Schemas.markdown Normal file
View file

@ -0,0 +1,37 @@
OpenPhoto
=======================
----------------------------------------
### What are schemas?
Schemas are the blueprint for various objects in the OpenPhoto platform.
The most logical example is the [Photo][Photo] object which represents a single photo in a user's photo collection.
Their photo library consists of a collection of [Photo][Photo] objects.
Other examples are a [User][User] object and [Action][Action] object.
----------------------------------------
### Why are schemas important?
By defining these schemas we enable different OpenPhoto applications to share the same data.
Since a [Photo][Photo] object has a predictable set of properties it means that any application can easily interact with it.
----------------------------------------
### Available schemas
1. [User][User] - Settings for a user.
1. [Credential][Credential] - Properties for a user's OAuth credential.
1. [Photo][Photo] - Properties for a single photo.
1. [Action][Action] - Comments and favorites on a photo.
1. [Tag][Tag] - Meta information for tags.
----------------------------------------
[User]: User.markdown
[Credential]: Credential.markdown
[Photo]: Photo.markdown
[Action]: Action.markdown
[Tag]: Tag.markdown

40
docs/schemas/Tag.markdown Normal file
View file

@ -0,0 +1,40 @@
Schema for a Tag object
=======================
----------------------------------------
### What's a Tag object for?
A Tag object stores information about a specific tag.
This includes but is not limited to the number of objects containing this tag.
The Tag objects schema is loose meaning that it can be flexible but at minimum it contains an `id` and `count`.
For example, the tag `sunnyvale` can have a `latitude` and `longitude` property.
----------------------------------------
### Schema for a Tag object
{
id: (string),
count: (int),
email: (string),
latitude: (float),
longitude: (float)
}
----------------------------------------
### Schema description
* id, Base 36 value of a base 10 auto-incremented value
* count, The number of objects with this tag
* email, Email address if applicable
* latitude, Latitude if applicable
* longitude, Longitude if applicable
[User]: http://theopenphotoproject.org/documentation/schemas/User
[Photo]: http://theopenphotoproject.org/documentation/schemas/Photo
[Action]: http://theopenphotoproject.org/documentation/schemas/Action
[Tag]: http://theopenphotoproject.org/documentation/schemas/Tag

32
docs/schemas/User.markdown Normal file
View file

@ -0,0 +1,32 @@
Schema for a User object
=======================
----------------------------------------
### What's a User object for?
The User object stores information for a given user.
This includes the last uploaded [Photo][Photo] and [Action][Action] id.
----------------------------------------
### Schema for a User object
{
id: (string),
lastPhotoId: (string),
lastActionId: (string)
}
----------------------------------------
### Schema description
* id, the user id
* lastPhotoId, most recent photo id
* lastActionId, most recent action id
[User]: http://theopenphotoproject.org/documentation/schemas/User
[Photo]: http://theopenphotoproject.org/documentation/schemas/Photo
[Action]: http://theopenphotoproject.org/documentation/schemas/Action

38
docs/schemas/Webhook.markdown Normal file
View file

@ -0,0 +1,38 @@
Schema for a Webhook object
=======================
----------------------------------------
### What's a Webhook object for?
Webhooks allow each OpenPhoto instance to be _programmable_.
Developers use webhooks to be notified of events so they can process them.
http://wiki.webhooks.org/w/page/13385124/FrontPage
----------------------------------------
### Schema for a Action object
{
id: (string),
appId: (string),
callback: (string),
topic: (enum),
verifyToken: (string),
challenge: (string),
secret: (string)
}
----------------------------------------
### Schema description
* id, A random unique 40 byte string to identify the webhook
* appId, A string identifing the application creating this entry
* callback, URL to which the event information is POSTed
* topic, An enumerated string with predefined values (i.e. photoupload, photoupdate, newcomment, etc.)
* verifyToken, A string supplied by the subscriber **not used for sync**
* challenge, A challenge string used in the verification process **not used for sync**
* secret, An optional subscriber supplied secret for request signing