diff options
| -rw-r--r-- | doc/about/about_hub.bb | 4 | ||||
| -rw-r--r-- | doc/about/about_hubzilla.bb | 123 | ||||
| -rw-r--r-- | doc/admin/administrator_guide.md | 48 | ||||
| -rw-r--r-- | doc/admin/hub_snapshots.md | 8 | ||||
| -rw-r--r-- | doc/dav_mount.bb | 3 | ||||
| -rw-r--r-- | doc/developer/api_zot.md | 77 | ||||
| -rw-r--r-- | doc/developer/developer_guide.md | 22 | ||||
| -rw-r--r-- | doc/member/member_faq.bb | 10 | ||||
| -rw-r--r-- | doc/member/member_guide.bb | 280 | ||||
| -rw-r--r-- | doc/toc.html | 2 | ||||
| -rw-r--r-- | doc/tutorials/personal_channel.html | 12 | ||||
| -rw-r--r-- | view/tpl/help.tpl | 6 |
12 files changed, 352 insertions, 243 deletions
diff --git a/doc/about/about_hub.bb b/doc/about/about_hub.bb index dde8950e5..0c1082f51 100644 --- a/doc/about/about_hub.bb +++ b/doc/about/about_hub.bb @@ -1,7 +1,7 @@ -[h1]Site Info[/h1] +[h3]Site Info[/h3] [list][*][url=[baseurl]/siteinfo]Site Info[/url] [*][url=[baseurl]/siteinfo/json]Site Info (JSON format)[/url][/list] -[h1]Terms of Service[/h1] +[h3]Terms of Service[/h3] [list][*][url=[baseurl]/help/TermsOfService]Terms of Service for this hub[/url][/list] #include doc/SiteTOS.md; diff --git a/doc/about/about_hubzilla.bb b/doc/about/about_hubzilla.bb index 61f5dd586..1117fd25a 100644 --- a/doc/about/about_hubzilla.bb +++ b/doc/about/about_hubzilla.bb @@ -1,8 +1,18 @@ -[h1]Project Overview[/h1] +[h3]Project Overview[/h3] $Projectname is a decentralized community server providing communications, identity, and access control services which work together seamlessly across domains and connected websites. It allows anybody to publicly or [b]privately[/b] publish a range of web/media/personal content. The cross-domain privacy implementation is unique and somewhat revolutionary, as identity and access rights are negotiated by servers invisibly in the background. + +$Projectname provides distributed web publishing and social communications with [b]decentralised permissions[/b]. + +So what exactly are "decentralised permissions"? They give me the ability to share something on my website (photos, media, files, webpages, etc.) with specific people on completely different websites - but not necessarily [i]everybody[/i] on those websites; and they do not need a password on my website and do not need to login to my website to view the things I've shared with them. They have one password on their own website and "magic authentication" between affiliated websites in the network. Also, as it is decentralised, there is no third party which has the ability to bypass permissions and see everything in the network. + +$Projectname combines many features of traditional blogs, social networking and media, content management systems, and personal cloud storage into an easy to use framework. Each node in the grid can operate standalone or link with other nodes to create a super-network; leaving privacy under the control of the original publisher. + +$Projectname is an open source webserver application written originally in PHP/MySQL and is easily installable by those with basic website administration skills. It is also easily extended via plugins and themes and other third-party tools. + + $Projectname is free and open source. It is designed to scale from a $35 Raspberry Pi, to top of the line AMD and Intel Xeon-powered multi-core enterprise servers. It can be used to support communication between a few individuals, or scale to many thousands and more. $Projectname aims to be skill and resource agnostic. It is easy to use by everyday people, as well as by systems administrators and developers. @@ -22,7 +32,7 @@ Along the way, $Projectname offers a number of unique goodies: [b]Privacy:[/b] $Projectname identities (Zot IDs) can be deleted, backed up/downloaded, and cloned. People have full control of their own data and content. Should you decide to delete all your content and erase your Zot ID, all you have to do is click on a link and it's immediately deleted from the hub. -[h2]Additional Resources and Links[/h2] +[h4]Additional Resources and Links[/h4] For more detailed, technical information about Zot, check out the following links: [list] [*][url=http://hubzilla.org]Hubzilla project website[/url] @@ -30,10 +40,10 @@ For more detailed, technical information about Zot, check out the following link [*][url=https://github.com/redmatrix/hubzilla-addons]Hubzilla official addons repository[/url] [/list] -[h2]$Projectname Governance[/h2] +[h4]$Projectname Governance[/h4] Governance relates to the management of a project and particularly how this relates to conflict resolution. -[h3]Community Governance[/h3] +[h5]Community Governance[/h5] The project is maintained and decisions made by the 'community'. The governance structure is still evolving. Until the structure is finalised, decisions are made in the following order: [ol] @@ -56,10 +66,10 @@ Community Voting does not always provide a pleasant outcome and can generate pol -[h2]Privacy Policy[/h2] +[h4]Privacy Policy[/h4] -[h3]Summary[/h3] +[h5]Summary[/h5] Q: Who can see my content? @@ -71,7 +81,7 @@ Q: Can my content be censored? A: $Projectname (the network) CANNOT censor your content. Server and hub administrators are subject to local laws and MAY remove objectionable content from their site/hub. Anybody MAY become a hub administrator, including you; and therefore publish content which might otherwise be censored. You still MAY be subject to local laws. -[h3]Definitions[/h3] +[h5]Definitions[/h5] **$Projectname** @@ -85,7 +95,7 @@ An individual computer or server connected to $Projectname. These are provided b The system operator of an individual hub. -[h3]Policies[/h3] +[h5]Policies[/h5] **Public Information** @@ -109,7 +119,7 @@ Comments to posts that were created by others and posts which are designated as $Projectname developers will ensure that any content you provide which is designated as PRIVATE will be protected against eavesdropping - to the best of their ability. Private channel content CAN be seen in the database of every involved hub administrator, but private messages are obscured in the database. The latter means that it is very difficult, but NOT impossible for this content to be seen by a hub administrator. Private channel content and private messages are also stripped from email notifications. End to end encryption is provided as an optional feature and this CANNOT be seen, even by a determined administrator. -[h3]Identity Privacy[/h3] +[h5]Identity Privacy[/h5] Privacy for your identity is another aspect. Because you have a decentralized identity in $Projectname, your privacy extends beyond your home hub. If you want to have complete control of your privacy and security you should run your own hub on a dedicated server. For many people, this is complicated and may stretch their technical abilities. So let's list a few precautions you can make to assure your privacy as much as possible. @@ -121,7 +131,7 @@ A decentralized identity has a lot of advantages and gives you al lot of interes * You can have a blocked hub. That means that all channels and content on that hub is not public, and not visible to the outside world. This is something only your hub administrator can do. We also respect this and automatically enable "Do Not Track" if it is set. -[h3]Censorship[/h3] +[h5]Censorship[/h5] $Projectname is a global network which is inclusive of all religions and cultures. This does not imply that every member of the network feels the same way you do on contentious issues, and some people may be STRONGLY opposed to the content you post. In general, if you wish to post something that you know may nor be universally acceptable, the best approach is to restrict the audience using privacy controls to a small circle of friends. @@ -131,32 +141,13 @@ $Projectname RECOMMENDS that hub administrators provide a grace period of 1-2 da If you typically and regularly post content of an adult or offensive nature, you are STRONGLY encouraged to mark your account "NSFW" (Not Safe For Work). This will prevent the display of your profile photo in the directory except to viewers that have chosen to disable "safe mode". If your profile photo is found by directory administrators to be adult or offensive, the directory administrator MAY flag your profile photo as NSFW. There is currently no official mechanism to contest or reverse this decision, which is why you SHOULD mark your own account NSFW if it is likely to be inappropriate for general audiences. -[h1]Features[/h1] - -[h2]$Projectname in a Nutshell[/h2] - -TL;DR - -$Projectname provides distributed web publishing and social communications with [b]decentralised permissions[/b]. - -So what exactly are "decentralised permissions"? They give me the ability to share something on my website (photos, media, files, webpages, etc.) with specific people on completely different websites - but not necessarily [i]everybody[/i] on those websites; and they do not need a password on my website and do not need to login to my website to view the things I've shared with them. They have one password on their own website and "magic authentication" between affiliated websites in the network. Also, as it is decentralised, there is no third party which has the ability to bypass permissions and see everything in the network. - -$Projectname combines many features of traditional blogs, social networking and media, content management systems, and personal cloud storage into an easy to use framework. Each node in the grid can operate standalone or link with other nodes to create a super-network; leaving privacy under the control of the original publisher. - -$Projectname is an open source webserver application written originally in PHP/MySQL and is easily installable by those with basic website administration skills. It is also easily extended via plugins and themes and other third-party tools. - -[h2]$Projectname Features[/h2] - +[h3]Features[/h3] $Projectname is a general-purpose web publishing and communication network, with several unique features. It is designed to be used by the widest range of people on the web, from non-technical bloggers, to expert PHP programmers and seasoned systems administrators. This page lists some of the core features of $Projectname that are bundled with the official release. As with most free and open source software, there may be many other extensions, additions, plugins, themes and configurations that are limited only by the needs and imagination of the members. -[h2]Built for Privacy and Freedom[/h2] - -One of the design goals of $Projectname is to enable easy communication on the web, while preserving privacy, if so desired by members. To achieve this goal, $Projectname includes a number of features allowing arbitrary levels of privacy: - -[h3]Affinity Slider[/h3] +[h4]Affinity Slider[/h4] When adding connnections in $Projectname, members have the option of assigning "affinity" levels (how close your friendship is) to the new connection. For example, when adding someone who happens to be a person whose blog you follow, you could assign their channel an affinity level of "Acquaintances". @@ -166,11 +157,11 @@ At this point, $Projectname [i]Affinity Slider[/i] tool, which usually appears a The Affinity Slider allows instantaneous filtering of large amounts of content, grouped by levels of closeness. -[h3]Connection Filtering[/h3] +[h4]Connection Filtering[/h4] You have the ability to control precisely what appears in your stream using the optional "Connection Filter". When enabled, the Connection Editor provides inputs for selecting criteria which needs to be matched in order to include or exclude a specific post from a specific channel. Once a post has been allowed, all comments to that post are allowed regardless of whether they match the selection criteria. You may select words that if present block the post or ensure it is included in your stream. Regular expressions may be used for even finer control, as well as hashtags or even the detected language of the post. -[h3]Access Control Lists[/h3] +[h4]Access Control Lists[/h4] When sharing content, members have the option of restricting who sees the content. By clicking on the padlock underneath the sharing box, one may choose desired recipients of the post, by clicking on their names. @@ -178,45 +169,45 @@ Once sent, the message will be viewable only by the sender and the selected reci Access Control Lists may be applied to content and posts, photos, events, webpages, chatrooms and files. -[h3]Single Sign-on[/h3] +[h4]Single Sign-on[/h4] Access Control Lists work for all channels in the grid due to our unique single sign-on technology. Most internal links provide an identity token which can be verified on other $Projectname sites and used to control access to private resources. You login once to your home hub. After that, authentication to all $Projectname resources is "magic". -[h3]WebDAV enabled File Storage[/h3] +[h4]WebDAV enabled File Storage[/h4] Files may be uploaded to your personal storage area using your operating system utilities (drag and drop in most cases). You may protect these files with Access Control Lists to any combination of $Projectname members (including some third party network members) or make them public. -[h3]Photo Albums[/h3] +[h4]Photo Albums[/h4] Store photos in albums. All your photos may be protected by Access Control Lists. -[h3]Events Calendar[/h3] +[h4]Events Calendar[/h4] Create and manage events and tasks, which may also be protected with Access Control Lists. Events can be imported/exported to other software using the industry standard vcalendar/iCal format and shared in posts with others. Birthday events are automatically added from your friends and converted to your correct timezone so that you will know precisely when the birthday occurs - no matter where you are located in the world in relation to the birthday person. Events are normally created with attendance counters so your friends and connections can RSVP instantly. -[h3]Chatrooms[/h3] +[h4]Chatrooms[/h4] You may create any number of personal chatrooms and allow access via Access Control Lists. These are typically more secure than XMPP, IRC, and other Instant Messaging transports, though we also allow using these other services via plugins. -[h3]Webpage Building[/h3] +[h4]Webpage Building[/h4] $Projectname has many "Content Management" creation tools for building webpages, including layout editing, menus, blocks, widgets, and page/content regions. All of these may be access controlled so that the resulting pages are private to their intended audience. -[h3]Apps[/h3] +[h4]Apps[/h4] Apps may be built and distributed by members. These are different from traditional "vendor lockin" apps because they are controlled completely by the author - who can provide access control on the destination app pages and charge accordingly for this access. Most apps in $Projectname are free and can be created easily by those with no programming skills. -[h3]Layout[/h3] +[h4]Layout[/h4] Page layout is based on a description language called Comanche. $Projectname is itself written in Comanche layouts which you can change. This allows a level of customisation you won't typically find in so-called "multi-user environments". -[h3]Bookmarks[/h3] +[h4]Bookmarks[/h4] Share and save/manage bookmarks from links provided in conversations. -[h3]Private Message Encryption and Privacy Concerns[/h3] +[h4]Private Message Encryption and Privacy Concerns[/h4] Private mail is stored in an obscured format. While this is not bullet-proof it typically prevents casual snooping by the site administrator or ISP. @@ -231,7 +222,7 @@ Private messages may be retracted (unsent) although there is no guarantee the re Posts and messages may be created with an expiration date, at which time they will be deleted/removed on the recipient's site. -[h3]Service Federation[/h3] +[h4]Service Federation[/h4] In addition to addon "cross-post connectors" to a variety of alternate networks, there is native support for importation of content from RSS/Atom feeds and using this to create special channels. Also, an experimental but working implementation of the Diaspora protocol allows communication with people on the Friendica and Diaspora decentralised social networks. This is currently marked experimental because these networks do not have the same level of privacy and encryption features and abilities as $Projectname and may present privacy risks. @@ -239,21 +230,21 @@ There is also experimental support for OpenID authentication which may be used i Channels may have permissions to become "derivative channels" where two or more existing channels combine to create a new topical channel. -[h3]Privacy Groups[/h3] +[h4]Privacy Groups[/h4] Our implementation of privacy groups is similar to Google "Circles" and Diaspora "Aspects". This allows you to filter your incoming stream by selected groups, and automatically set the outbound Access Control List to only those in that privacy group when you post. You may over-ride this at any time (prior to sending the post). -[h3]Directory Services[/h3] +[h4]Directory Services[/h4] We provide easy access to a directory of members and provide decentralised tools capable of providing friend "suggestions". The directories are normal $Projectname sites which have chosen to accept the directory server role. This requires more resources than most typical sites so is not the default. Directories are synchronised and mirrored so that they all contain up-to-date information on the entire network (subject to normal propagation delays). -[h3]TLS/SSL[/h3] +[h4]TLS/SSL[/h4] For $Projectname hubs that use TLS/SSL, client to server communications are encrypted via TLS/SSL. Given recent disclosures in the media regarding widespread, global surveillance and encryption circumvention by the NSA and GCHQ, it is reasonable to assume that HTTPS-protected communications may be compromised in various ways. Private communications are consequently encrypted at a higher level before sending offsite. -[h3]Channel Settings[/h3] +[h4]Channel Settings[/h4] When a channel is created, a role is chosen which applies a number of pre-configured security and privacy settings. These are chosen for best practives to maintain privacy at the requested levels. @@ -270,12 +261,12 @@ The options are: - Anybody on the Internet. -[h3]Public and Private Forums[/h3] +[h4]Public and Private Forums[/h4] Forums are typically channels which may be open to participation from multiple authors. There are currently two mechanisms to post to forums: 1) "wall-to-wall" posts and 2) via forum @mention tags. Forums can be created by anybody and used for any purpose. The directory contains an option to search for public forums. Private forums can only be posted to and often only seen by members. -[h3]Account Cloning[/h3] +[h4]Account Cloning[/h4] Accounts in $Projectname are referred to as [i]nomadic identities[/i], because a member's identity is not bound to the hub where the identity was originally created. For example, when you create a Facebook or Gmail account, it is tied to those services. They cannot function without Facebook.com or Gmail.com. @@ -295,53 +286,53 @@ $Projectname offers interesting new possibilities for privacy. You can read more Some caveats apply. For a full explanation of identity cloning, read the <HOW TO CLONE MY IDENTITY>. -[h3]Multiple Profiles[/h3] +[h4]Multiple Profiles[/h4] Any number of profiles may be created containing different information and these may be made visible to certain of your connections/friends. A "default" profile can be seen by anybody and may contain limited information, with more information available to select groups or people. This means that the profile (and site content) your beer-drinking buddies see may be different than what your co-workers see, and also completely different from what is visible to the general public. -[h3]Account Backup[/h3] +[h4]Account Backup[/h4] Red offers a simple, one-click account backup, where you can download a complete backup of your profile(s). Backups can then be used to clone or restore a profile. -[h3]Account Deletion[/h3] +[h4]Account Deletion[/h4] Accounts can be immediately deleted by clicking on a link. That's it. All associated content is then deleted from the grid (this includes posts and any other content produced by the deleted profile). Depending on the number of connections you have, the process of deleting remote content could take some time but it is scheduled to happen as quickly as is practical. -[h3][size=20]Content Creation[/h2] +[h4]Content Creation[/h4] -[h3]Writing Posts[/h3] +[h4]Writing Posts[/h4] $Projectname supports a number of different ways of adding rich-text content. The default is a custom variant of BBcode, tailored for use in $Projectname. You may also enable the use of Markdown if you find that easier to work with. A visual editor may also be used. The traditional visual editor for $Projectname had some serious issues and has since been removed. We are currently looking for a replacement. When creating "Websites", content may be entered in HTML, Markdown, BBcode, and/or plain text. -[h3]Deletion of content[/h3] +[h4]Deletion of content[/h4] Any content created in $Projectname remains under the control of the member (or channel) that originally created it. At any time, a member can delete a message, or a range of messages. The deletion process ensures that the content is deleted, regardless of whether it was posted on a channel's primary (home) hub, or on another hub, where the channel was remotely authenticated via Zot ($Projectname communication and authentication protocol). -[h3]Media[/h3] +[h4]Media[/h4] Similar to any other modern blogging system, social network, or a micro-blogging service, $Projectname supports the uploading of files, embedding of videos, linking web pages. -[h3]Previewing/Editing[/h3] +[h4]Previewing/Editing[/h4] Post can be previewed prior to sending and edited after sending. -[h3]Voting/Consensus[/h3] +[h4]Voting/Consensus[/h4] Posts can be turned into "consensus" items which allows readers to offer feedback, which is collated into "agree", "disagree", and "abstain" counters. This lets you gauge interest for ideas and create informal surveys. -[h3]Extending $Projectname[/h3] +[h4]Extending $Projectname[/h4] $Projectname can be extended in a number of ways, through site customisation, personal customisation, option setting, themes, and addons/plugins. -[h3]API[/h3] +[h4]API[/h4] An API is available for use by third-party services. This is based originally on the early Twitter API (for which hundreds of third-party tools exist). It is currently being extended to provide access to facilities and abilities which are specific to $Projectname. Access may be provided by login/password or OAuth and client registration of OAuth applications is provided. -[h1]What is Zot?[/h1] +[h3]What is Zot?[/h3] Zot is the protocol that powers $Projectname, providing three core capabilities: Communications, Identity, and Access Control. @@ -350,7 +341,7 @@ The functionality it provides can also be described as follows: - a relationship online is just a bunch of permissions - the internet is just another folder -[h2]Communications[/h2] +[h4]Communications[/h4] Zot is a revolutionary protocol which provides [i]decentralised communications[/i] and [i]identity management[/i] across the grid. The resulting platform can provide web services comparable to those offered by large corporate providers, but without the large corporate provider and their associated privacy issues, insatiable profit drive, and walled-garden mentality. @@ -360,7 +351,7 @@ Zot allows a wide array of background services in the grid, from offering friend You won't find these features at all on other decentralized communication services. In addition to providing hub (server) decentralization, perhaps the most innovative and interesting Zot feature is its provision of [i]decentralized identity[/i] services. -[h2]Identity[/h2] +[h4]Identity[/h4] Zot's identity layer is unique. It provides [i]invisible single sign-on[/i] across all sites in the grid. @@ -380,7 +371,7 @@ You login only once on your home hub (or any nomadic backup hub you have chosen) You cannot be silenced. You cannot be removed from the grid, unless you yourself choose to exit it. -[h2]Access Control[/h2] +[h4]Access Control[/h4] Zot's identity layer allows you to provide fine-grained permissions to any content you wish to publish - and these permissions extend across $Projectname. This is like having one super huge website made up of an army of small individual websites - and where each channel in the grid can completely control their privacy and sharing preferences for any web resources they create. @@ -391,7 +382,7 @@ This type of control is available on large corporate providers such as Facebook Access can be granted or denied for any resource, to any channel, or any group of channels; anywhere within the grid. Others can access your content if you permit them to do so, and they do not even need to have an account on your hub. Your private photos cannot be viewed, because permission really work; they are not an addon that was added as an afterthought. If you aren't on the list of allowed viewers for a particular photo, you aren't going to look at it. -[h1]Credits[/h1] +[h3]Credits[/h3] Thanks to all who have helped and contributed to the project and its predecessors over the years. It is possible we missed in your name but this is unintentional. We also thank the community and diff --git a/doc/admin/administrator_guide.md b/doc/admin/administrator_guide.md index bb5c821ee..219673c50 100644 --- a/doc/admin/administrator_guide.md +++ b/doc/admin/administrator_guide.md @@ -1,5 +1,5 @@ -# Overview +### Overview $Projectname is more than a simple web application. It is a complex communications system which more closely resembles an email server @@ -16,7 +16,7 @@ websites. It will run on most any Linux VPS system. Windows LAMP platforms such as XAMPP and WAMP are not officially supported at this time however we welcome patches if you manage to get it working. -# Where to find more help +### Where to find more help If you encounter problems or have issues not addressed in this documentation, please let us know via the [Github issue tracker](https://github.com/redmatrix/hubzilla/issues). Please be as clear as you @@ -27,14 +27,14 @@ in existence we may have only limited ability to debug your PHP installation or acquire any missing modules * but we will do our best to solve any general code issues. -# Before you begin +### Before you begin -## Choose a domain name or subdomain name for your server +#### Choose a domain name or subdomain name for your server $Projectname can only be installed into the root of a domain or sub-domain, and can not be installed using alternate TCP ports. -## Decide if you will use SSL and obtain an SSL certificate before software installation +#### Decide if you will use SSL and obtain an SSL certificate before software installation You SHOULD use SSL. If you use SSL, you MUST use a "browser-valid" certificate. *You MUST NOT use self-signed certificates!* @@ -74,14 +74,14 @@ it is installed, and an existing directory in this location may prevent some of these services from working correctly. This should not be a problem with Apache, but may be an issue with nginx or other web server platforms. -# Deployment +### Deployment There are several ways to deploy a new hub. * Manual installation on an existing server * Automated installation on an existing server using a shell script * Automated deployment using an OpenShift virtual private server (VPS) -# Requirements +### Requirements * Apache with mod-rewrite enabled and "AllowOverride All" so you can use a local .htaccess file. Some folks have successfully used nginx and lighttpd. Example config scripts are available for these platforms in doc/install. @@ -111,7 +111,7 @@ PHP might differ from the _webserver_ version # Manual Installation # -## Unpack the $Projectname files into the root of your web server document area ### +#### Unpack the $Projectname files into the root of your web server document area ### If you copy the directory tree to your webserver, make sure that you include the hidden files like .htaccess. @@ -148,14 +148,14 @@ web-based administrative tools to function: * `view/theme` * `widget` -## Official addons -### Installation +#### Official addons +##### Installation Navigate to your webThen you should clone the addon repository (separately). We'll give this repository a nickname of 'hzaddons'. You can pull in other hubzilla addon repositories by giving them different nicknames:: cd mywebsite util/add_addon_repo https://github.com/redmatrix/hubzilla-addons.git hzaddons -### Updating +##### Updating For keeping the addon tree updated, you should be on your top level website directory and issue an update command for that repository:: cd mywebsite @@ -167,10 +167,10 @@ Create searchable representations of the online documentation. You may do this cd mywebsite util/importdoc -# Automated installation via the .homeinstall shell script +### Automated installation via the .homeinstall shell script There is a shell script in (``.homeinstall/hubzilla-setup.sh``) that will install $Projectname and its dependencies on a fresh installation of Debian 8.3 stable (Jessie). It should work on similar Linux systems but your results may vary. -## Requirements +#### Requirements The installation script was originally designed for a small hardware server behind your home router. However, it has been tested on several systems running Debian 8.3: * Home-PC (Debian-8.3.0-amd64) @@ -183,7 +183,7 @@ The installation script was originally designed for a small hardware server behi * DigitalOcean droplet (Debian 8.3 x64 / 512 MB Memory / 20 GB Disk / NYC3) -## Overview of installation steps +#### Overview of installation steps 1. `apt-get install git` 1. `mkdir -p /var/www/html` 1. `cd /var/www/html` @@ -196,7 +196,7 @@ The installation script was originally designed for a small hardware server behi 1. `service apache2 reload` 1. Open your domain with a browser and step throught the initial configuration of $Projectname. -# Service Classes +### Service Classes Service classes allow you to set limits on system resources by limiting what individual accounts can do, including file storage and top-level post limits. Define custom service @@ -262,8 +262,8 @@ set the account that owns channel 'blogchan' to service class 'firstclass' (with * chatters_inroom - maximum chatters per room * access_tokens - maximum number of Guest Access Tokens per channel -# Theme management -## Repo management example +### Theme management +#### Repo management example 1. Navigate to your hub web root ``` @@ -280,9 +280,9 @@ set the account that owns channel 'blogchan' to service class 'firstclass' (with root@hub:/var/www# util/update_theme_repo DeadSuperHero ``` -# Channel Directory +### Channel Directory -## Keywords +#### Keywords There is a "tag cloud" of keywords that can appear on the channel directory page. If you wish to hide these keywords, which are drawn from the directory server, you @@ -296,9 +296,9 @@ empty: util/config system directory_server "" -# Upgrading from RedMatrix to $Projectname +### Upgrading from RedMatrix to $Projectname -## How to migrate an individual channel from RedMatrix to $Projectname +#### How to migrate an individual channel from RedMatrix to $Projectname 1. Clone the channel by opening an account on a $Projectname hub and performing a basic import (not content) from the original RedMatrix hub. Give your new clone time to sync connections and settings. 1. Export individual channel content from your RedMatrix hub to a set of JSON text files using the red.hub/uexport tool. Do this in monthly increments if necessary. @@ -307,8 +307,8 @@ empty: 1. After successful import (check!) delete your channel on the old RedMatrix Server. 1. On the $Projectname server visit new.hub/locs and upgrade to your channel to a primary one. And when the old Redmatrix server is still listed delete them here as well. Press "Sync" to inform all other server in the grid. -# Troubleshooting -## Log files +### Troubleshooting +#### Log files There are three different log facilities. @@ -338,7 +338,7 @@ git checkout file.php To immediately clear out all the extra logging stuff you added. Use the information from this log and any detail you can provide from your investigation of the problem to file your bug report - unless your analysis points to the source of the problem. In that case, just fix it. -### Rotating log files +##### Rotating log files 1. Enable the **logrot** addon in the official [hubzilla-addons](https://github.com/redmatrix/hubzilla-addons) repo 1. Create a directory in your web root called `log` with webserver write permissions diff --git a/doc/admin/hub_snapshots.md b/doc/admin/hub_snapshots.md index 7e4ba95b2..ab0948aa8 100644 --- a/doc/admin/hub_snapshots.md +++ b/doc/admin/hub_snapshots.md @@ -1,4 +1,4 @@ -# Hub Snapshot Tools +### Hub Snapshot Tools Hubzilla developers frequently need to switch between branches that might have incompatible database schemas or content. The following two scripts create and @@ -7,7 +7,7 @@ root and the entire database state. Each script requires a config file called `hub-snapshot.conf` residing in the same folder and containing the specific directories and database details of your hub. -# Config +### Config The format of the config file is very strict. There must be no spaces between the variable name and the value. Replace only the content inside the quotes with your @@ -24,7 +24,7 @@ configuration. Save this file as `hub-snapshot.conf` alongside the scripts. # The target snapshot folder where the git repo will be initialized SNAPSHOTROOT="/root/snapshots/hubzilla/" -# Snapshot +### Snapshot Example usage: @@ -84,7 +84,7 @@ Example usage: exit 0 -# Restore +### Restore #!/bin/bash # Restore hub to a previous state. Input hub config and commit hash diff --git a/doc/dav_mount.bb b/doc/dav_mount.bb index 0fd3d4691..94db18ac7 100644 --- a/doc/dav_mount.bb +++ b/doc/dav_mount.bb @@ -81,6 +81,3 @@ Unmount your file system, remount your file system, and try copying over a file If that still doesn't work, disable the cache. Note that this has a performance impact so should only be done if disabling locks didn't solve your problem. Edit the cache_size and set it to [code]cache_size 0[/code] and also set file_refresh to [code]file_refresh 0[/code]. Unmount your filesystem, remount your file system, and test it again.
If it [i]still[/i] doesn't work, there is one more thing you can try. (This one is caused by a bug in older versions of dav2fs itself, so updating to a new version may also help). Enable weak etag dropping by setting [code]drop_weak_etags 1[/code]. Unmount and remount your filesystem to apply the changes.
-
-#include doc/macros/cloud_footer.bb;
-
diff --git a/doc/developer/api_zot.md b/doc/developer/api_zot.md index 2458da8b2..d46cc8860 100644 --- a/doc/developer/api_zot.md +++ b/doc/developer/api_zot.md @@ -1,30 +1,27 @@ -Zot API -======= +### Zot API The API endpoints detailed below are relative to `api/z/1.0`, meaning that if an API is listed as `channel/stream` the full API URL is `[baseurl]/api/z/1.0/channel/stream` -channel/export/basic -================================================================================ +### channel/export/basic Export channel data -channel/stream -================================================================================ +### channel/stream Fetch channel conversation items -network/stream -================================================================================ +### network/stream + Fetch network conversation items -files -================================================================================ +### files + List file storage (attach DB) @@ -130,13 +127,13 @@ Returns: -filemeta -================================================================================ +### filemeta + Export file metadata for any uploaded file -filedata -================================================================================ +### filedata + Provides the ability to download a file from cloud storage in chunks @@ -203,14 +200,14 @@ Returns: } -file/export -================================================================================ +### file/export + -file -================================================================================ +### file + + +### albums -albums -================================================================================ Description: list photo albums @@ -278,18 +275,18 @@ Example: -photos -================================================================================ +### photos + list photo metadata -photo -================================================================================ +### photo + -group -================================================================================ +### group + `GET /api/z/1.0/group` @@ -328,8 +325,8 @@ To use with API group_members, provide either 'group_id' from the id element ret } ] -group_members -================================================================================ +### group_members + `GET /api/z/1.0/group_members` @@ -461,8 +458,8 @@ group_member+abook+xchan (DB join) for each member of the privacy group ] -xchan -================================================================================ +### xchan + An xchan is a global location independent channel and is the primary record for a network identity. It may refer to channels on other websites, networks, or services. @@ -506,8 +503,8 @@ Returns: "deleted": "0" } -item/update -================================================================================ +### item/update + Create or update an item (post, activity, webpage, etc.) @@ -733,22 +730,22 @@ Returns: } -item/full -================================================================================ +### item/full + Get all data associated with an item -abook -================================================================================ +### abook + Connections -abconfig -================================================================================ +### abconfig + Connection metadata (such as permissions) -perm_allowed -================================================================================ +### perm_allowed + Check a permission for a given xchan diff --git a/doc/developer/developer_guide.md b/doc/developer/developer_guide.md index 7ec76714f..fa50de8a1 100644 --- a/doc/developer/developer_guide.md +++ b/doc/developer/developer_guide.md @@ -1,4 +1,4 @@ -# Who is a Hubzilla developer? Should I read this? +### Who is a Hubzilla developer? Should I read this? Anyone who contributes to making Hubzilla better is a developer. There are many different and important ways you can contribute to this amazing technology, _even if you do not know how to write code_. The software itself is only a part of the Hubzilla project. You can contribute by @@ -11,31 +11,31 @@ _Software_ developers are of course welcomed; there are so many great ideas to i This document will help you get started learning and contributing to Hubzilla. -# Versioning system +### Versioning system The versioning system is similar to the popular semantic versioning but less stringent. Given x.y.z, x changes yearly. y changes for "stable" monthly builds, and z increments when there are interface changes. We maintain our date and build numbers for medium grain version control (commits within a certain date range) and of course git revs for fine grained control. -# Git repository branches +### Git repository branches There are two official branches of the Hubzilla git repo. * The stable version is maintained on the **master** branch. The latest commit in this branch is considered to be suitable for production hubs. * Experimental development occurs on the **dev** branch, which is merged into **master** when it is deemed tested and stable enough. -# Developer tools and workflows +### Developer tools and workflows -## Hub Snapshots +#### Hub Snapshots -The [[Hub Snapshots]] page provides instructions and scripts for taking complete +The [hub snapshots](/help/admin/hub_snapshots) page provides instructions and scripts for taking complete snapshots of a hub to support switching between consistent and completely known states. This is useful to prevent situations where the content or database schema might be incompatible with the code. -# Translations +### Translations Our translations are managed through Transifex. If you wish to help out translating Hubzilla to another language, sign up on transifex.com, visit [https://www.transifex.com/projects/p/red-matrix/](https://www.transifex.com/projects/p/red-matrix/) and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files. -## Translation Process +#### Translation Process The strings used in the UI of Hubzilla is translated at [Transifex][1] and then included in the git repository at github. If you want to help with translation @@ -98,7 +98,7 @@ view/de/hmessages.po you would do the following. repository, push it to your fork of the Hubzilla repository at github and issue a pull request for that commit. -## Utilities +#### Utilities Additional to the po2php script there are some more utilities for translation in the "util" directory of the Hubzilla source tree. If you only want to @@ -108,7 +108,7 @@ works. For further information see the utils/README file. -## Known Problems +#### Known Problems * Hubzilla uses the language setting of the visitors browser to determain the language for the UI. Most of the time this works, but there are some known @@ -116,7 +116,7 @@ For further information see the utils/README file. * the early translations are based on the friendica translations, if you some rough translations please let us know or fix them at Transifex. -# To-be-organized information +### To-be-organized information **Here is how you can join us.** diff --git a/doc/member/member_faq.bb b/doc/member/member_faq.bb index bb70dc4d9..9533cb557 100644 --- a/doc/member/member_faq.bb +++ b/doc/member/member_faq.bb @@ -1,10 +1,10 @@ -[h1]$Projectname FAQ[/h1] -[h2]I am able to edit a post's text after I saved it, but is there a way to change the permissions?[/h2] +[h3]$Projectname FAQ[/h3] +[h4]I am able to edit a post's text after I saved it, but is there a way to change the permissions?[/h4] Short anser: No, there isn't. There are reasons. You are able to change permissons to your files, photos and the likes, but not to posts after you have saved them. The main reason is: Once you have saved a post it is being distributed either to the public channel and from there to other $Projectname servers or to those you intended it to go. Just like you cannot reclaim something you gave to another person, you cannot change permissions to $Projectname posts. We would need to track everywhere your posting goes, keep track of everyone you allowed to see it and then keep track of from whom to delete it. If a posting is public this is even harder, as $Projectname is a global network and there is no way to follow a post, let alone reclaim it reliably. Other networks that may receive your post have no reliable way to delete or reclaim the post. -[h2]I downloaded my channel and imported it (cloned my identity) to another site but there is no content, no posts, no photos. What is wrong???[/h2] +[h4]I downloaded my channel and imported it (cloned my identity) to another site but there is no content, no posts, no photos. What is wrong???[/h4] Posts and photos/files are provided separately from the channel basic information. This is due to memory limitations dealing with years of conversations and photo archives. Posts and conversations can be synced separately from the basic channel information. Photos and file archives can be transferred using a plugin tool such as 'redfiles', which is currently listed as "experimental". When creating this feature we thought that keeping all your contacts was the most important task. Your friends have already seen your old content. Posts/conversations were next in priority and these may now be synced. Files and photos are the last bit to get completely working. Once we find someone willing to finish implementing this, it will be done. :) -[h2]I can't see private resources[/h2] +[h4]I can't see private resources[/h4] You have probably disabled third party cookies. You need to enable them for remote authentication to work. -[h2]There are a lot of foreign language posts. Let's auto-translate them.[/h2] +[h4]There are a lot of foreign language posts. Let's auto-translate them.[/h4] There are also a lot of [b]private[/b] foreign language posts and auto-translation services would require us to transmit these private messages to the translation service; and we don't know what they will do with them on their servers. Actually we do know thanks to Edward Snowden. Our best bet is a project called [b][i]Apertium[/i][/b] which is an open source translator we can install locally. It is currently missing German translations - which are the most requested translation in the matrix. Once again, this will be implemented when we find somebody who really wants to make it happen. diff --git a/doc/member/member_guide.bb b/doc/member/member_guide.bb index 9824de390..53cc6b8c7 100644 --- a/doc/member/member_guide.bb +++ b/doc/member/member_guide.bb @@ -1,8 +1,8 @@ -[h1]Overview[/h1] +[h3]Overview[/h3] While many features and capabilities of $Projectname are familiar to people who have used social networking sites and blogging software, there are also quite a few new concepts and features that most people have not encountered before. Some of the new ideas are related to the decentralized nature of the grid; others are associated with the advanced permissions system that is necessary to protect your data privacy. The purpose of this guide is to help you understand how to create, configure, and use your nomadic identity. -[h1]Registration[/h1] +[h3]Registration[/h3] Not all $Projectname sites allow open registration. If registration is allowed, you will see a "Register" link immediately below the login prompts on the site home page. Following this link will take you to the site Registration page. On some sites it may redirect you to another site which allow registrations. As all $Projectname sites are linked, it does not matter where your account resides. @@ -71,46 +71,10 @@ See Also [zrl=[baseurl]/help/AdvancedSearch]Advanced Searching[/zrl] -[h2]Channels[/h2] +[h3]Account Permission Roles[/h3] -[h3]What are channels?[/h3] - -Channels are simply collections of content stored in one place. A channel can represent anything. It could represent you, a website, a forum, photo albums, anything. For most people, their first channel with be "Me". - -The most important features for a channel that represents "me" are: -[ul] -[*]Secure and private "spam free" communications - -[*]Identity and "single-signon" across the entire network - -[*]Privacy controls and permissions which extend to the entire network - -[*]Directory services (like a phone book) -[/ul] -In short, a channel that represents yourself is "me, on the internet". - -[h3]Creating channels[/h3] - -You will be required to create your first channel as part of the sign up process. You can also create additonal channels from the "Select channel" link. - -You will be asked to provide a channel name, and a short nick name. For a channel that represents yourself, it is a good idea to use your real name here to ensure your friends can find you, and connect to your channel. The short nickname will be used to generate a "webbie". This is a bit like a username, and will look like an email address, taking the form nickname@domain. You should put a little thought into what you want to use here. Imagine somebody asking for your webbie and having to tell them it is "llamas-are_kewl.123". "llamasarecool" would be a much better choice. - -Once you have created your channel, you will be taken to the settings page, where you can configure your channel, and set your default permissions. - -Once you have done this, your channel is ready to use. At [observer=1][observer.url][/observer][observer=0][baseurl]/channel/username[/observer] you will find your channel "stream". This is where your recent activity will appear, in reverse chronological order. If you post in the box marked "share", the entry will appear at the top of your stream. You will also find links to all the other communication areas for this channel here. The "About" tab contains your "profile", the photos page contain photo albums, and the events page contains events share by both yourself and your contacts. - -[h3]The grid, permissions and delegation[/h3] - -The "Grid" page contains all recent posts from across $Projectname network, again in reverse chronologial order. The exact posts that appear here depend largely on your permissions. At their most permissive, you will receive posts from complete strangers. At the other end of the scale, you may see posts from only your friends - or if you're feeling really anti-social, only your own posts. - -As mentioned at the start, many other kinds of channel are possible, however, the creation procedure is the same. The difference between channels lies primarily in the permissions assigned. For example, a channel for sharing documents with colleagues at work would probably want more permissive settings for "Can write to my "public" file storage" than a personal account. For more information, see the [zrl=[baseurl]/help/roles]permissions section[/zrl]. - -You can also delegate control of your channels' posts and connections, but not its configurations, to another channel. That is done by editing a connection and assigning it the permission to administer your channel's resources. - -[h1]Account Permission Roles[/h1] - -[h2]Social[/h2] +[h4]Social[/h4] [b]Mostly Public[/b] @@ -126,7 +90,7 @@ By default all posts and published items are sent to your 'Friends' privacy grou By default all posts and published items are sent to your 'Friends' privacy group. New friends are added to this privacy group. You can over-ride this and create a public post or public item if you desire. You are NOT listed in the directory. Only your connections can see your other connections. Your online presence is hidden. -[h2]Forum[/h2] +[h4]Forum[/h4] [b]Mostly Public[/b] @@ -142,7 +106,7 @@ By default all posts and published items are sent to the channel's 'Friends' pri By default all posts and published items are sent to your 'Friends' privacy group. New friends are added to this privacy group. The owner can over-ride this and create a public post or public item if desired. Members cannot. You are NOT listed in the directory. Only your connections can see your other connections. Your online presence is hidden. Members must be manually added by the forum owner. Posting by @mention+ is disabled. Posts can only be made via wall-to-wall posts, and sent to members of the 'Friends' privacy group. They are not publicly visible. -[h2]Feed[/h2] +[h4]Feed[/h4] [b]Public[/b] @@ -155,7 +119,7 @@ Similiar to Social - Mostly Public, but tailored for RSS feed sources. Items may Not listed in directory. Online presence is meaningless, therefore hidden. Feed is published only to members of the 'Friends' privacy group. New connections are automatically added to this privacy group. Members must be manually approved by the channel owner. -[h2]Special[/h2] +[h4]Special[/h4] [b]Celebrity/Soapbox[/b] @@ -167,12 +131,48 @@ Listed in directory. Communications are by default public. Online presence is hi A public forum which allows members to post files/photos/webpages. -[h2]Custom/Expert Mode[/h2] +[h4]Custom/Expert Mode[/h4] Set all the privacy and permissions manually to suit your specific needs. -[h1]Connecting To Channels[/h1] +[h3]Channels[/h3] + +[h4]What are channels?[/h4] + +Channels are simply collections of content stored in one place. A channel can represent anything. It could represent you, a website, a forum, photo albums, anything. For most people, their first channel with be "Me". + +The most important features for a channel that represents "me" are: +[ul] +[*]Secure and private "spam free" communications + +[*]Identity and "single-signon" across the entire network + +[*]Privacy controls and permissions which extend to the entire network + +[*]Directory services (like a phone book) +[/ul] +In short, a channel that represents yourself is "me, on the internet". + +[h4]Creating channels[/h4] + +You will be required to create your first channel as part of the sign up process. You can also create additonal channels from the "Select channel" link. + +You will be asked to provide a channel name, and a short nick name. For a channel that represents yourself, it is a good idea to use your real name here to ensure your friends can find you, and connect to your channel. The short nickname will be used to generate a "webbie". This is a bit like a username, and will look like an email address, taking the form nickname@domain. You should put a little thought into what you want to use here. Imagine somebody asking for your webbie and having to tell them it is "llamas-are_kewl.123". "llamasarecool" would be a much better choice. + +Once you have created your channel, you will be taken to the settings page, where you can configure your channel, and set your default permissions. + +Once you have done this, your channel is ready to use. At [observer=1][observer.url][/observer][observer=0][baseurl]/channel/username[/observer] you will find your channel "stream". This is where your recent activity will appear, in reverse chronological order. If you post in the box marked "share", the entry will appear at the top of your stream. You will also find links to all the other communication areas for this channel here. The "About" tab contains your "profile", the photos page contain photo albums, and the events page contains events share by both yourself and your contacts. + +[h4]The grid, permissions and delegation[/h4] + +The "Grid" page contains all recent posts from across $Projectname network, again in reverse chronologial order. The exact posts that appear here depend largely on your permissions. At their most permissive, you will receive posts from complete strangers. At the other end of the scale, you may see posts from only your friends - or if you're feeling really anti-social, only your own posts. + +As mentioned at the start, many other kinds of channel are possible, however, the creation procedure is the same. The difference between channels lies primarily in the permissions assigned. For example, a channel for sharing documents with colleagues at work would probably want more permissive settings for "Can write to my "public" file storage" than a personal account. For more information, see the [zrl=[baseurl]/help/roles]permissions section[/zrl]. + +You can also delegate control of your channels' posts and connections, but not its configurations, to another channel. That is done by editing a connection and assigning it the permission to administer your channel's resources. + +[h3]Connecting To Channels[/h3] Connections in $Projectname can take on a great many different meanings. But let's keep it simple, you want to be friends with somebody like you are familiar with from social networking. How do you do it? @@ -186,7 +186,7 @@ Visit their profile by clicking their photograph in the directory, matrix, or co You may also connect with any channel by visiting the "Connections" page of your site or the Directory and typing their "webbie" into the "Add New Connection" field. Use this method if somebody tells you their webbie and you wish to connect with them. A webbie looks like an email address; for example "bob@example.com". The process is the same as connecting via the "Connect" button - you will then be taken to the connection editor to set permissions. -[h2] Block/Ignore/Archive/Hide channels [/h2] +[h4] Block/Ignore/Archive/Hide channels [/h4] Channels in your address book can have statuses such as [i]blocked[/i], [i]ignored[/i], [i]archived[/i] and [i]hidden[/i]. From your connections page you can see tabs that display the channels with those statuses. From your edit connection pages you can change the statuses of a channel. @@ -200,23 +200,23 @@ Here's their meaning: [b]Archived:[/b] if a channel can't be reached for 30 days, it is automatically marked as archived. This keeps all the data but stops polling the channel for new information and removes it from autocomplete. If later you learn the channel has come back online, you may manually unarchive it. -[h2]Premium Channels[/h2] +[h4]Premium Channels[/h4] Some channels are designated "Premium Channels" and may require some action on your part before a connection can be established. The Connect button will for these channels will take you to a page which lists in detail what terms the channel owner has set. If the terms are accepted, the connection will then proceed normally. In some cases, such as with celebrities and world-reknowned publishers, this may involve payment. If you do not agree to the terms, the connection will not proceed, or it may proceed but with reduced permissions allowed on your interactions with that channel. -[h1]Permissions[/h1] +[h3]Permissions[/h3] Permissions in $Projectname are more complete than you may be used to. This allows us to define more fine graded relationships than the black and white "this person is my friend, so they can do everything" or "this person is not my friend, so they can't do anything" permissions you may find elsewhere. -[h2]Permission Roles[/h2] +[h4]Permission Roles[/h4] When you create a channel we allow you to select different 'roles' for that channel. These create an entire family of permissions and privacy settings that are appropriate for that role. Typical roles are "Social - mostly public", "Social - mostly private", "Forum - public" and many others. These bring a level of simplicity to managing permissions. Just choose a role and appropriate permissions are automatically applied. You can also choose 'Custom/Expert mode' and change any individual permission setting in any way you desire. -[h2]Default Permission Limits[/h2] +[h4]Default Permission Limits[/h4] There are a large number of individual permissions. These control everything from the ability to view your stream to the ability to chat with you. Every permission has a limit. The scope of these permissions varies from "Only me" to "Everybody on the internet" - though some scopes may not be available for some permissions. The limit applies to any published thing you create which has no privacy or access control. For example if you publish a photo and didn't select a specific audience with permission to view it, we apply the limit. These limits apply to everything within that permission rule, so you cannot apply a limit to one photo. The limit applies to all your photos. If all your photos are visible to everybody on the internet and you reduce the limit only to friends, [b]all[/b] of your photos will now be visible only to friends. -[h2]Access Control[/h2] +[h4]Access Control[/h4] Access Control is the preferred method of managing privacy in [i]most[/i] cases, rather than using permission limits. This creates lists of either connections or privacy groups (or both) and uses the access list to decide if a permission is allowed. An access list is attached to everything you publish. Unlike permission limits, if you change the access control list on a single photo, it doesn't affect any of your other photos. You can use privacy groups and a "default access control list" to create and automate the management of access control lists to provide any level of privacy you desire on anything you publish. @@ -281,13 +281,13 @@ Plugins/addons may provide special permission settings, so you may be offered ad If you have set any of these permissions to "only those I specifically allow", you may specify indivudal permissions on the connnection edit screen. -[h2]Affinity[/h2] +[h4]Affinity[/h4] The connection edit screen offers a slider to select a degree of friendship with the connnection (this tool is enabled through the "Extra Features" tab of your Settings page). Think of this as a measure of how much you like or dislike them. 1 is for people you like, whose posts you want to see all the time. 99 is for people you don't care for, and whose posts you might only wish to look at occasionally. Once you've assigned a value here, you can use the affinity tool on the matrix page to filter content based on this number. The slider on the matrix page has both a minimum and maximum value. Posts will only be shown from people who fall between this range. Affinity has no relation to permissions, and is only useful in conjunction with the affinity tool feature. -[h1]Personal Cloud Storage[/h1] +[h3]Personal Cloud Storage[/h3] $Projectname provides an ability to store privately and/or share arbitrary files with friends. @@ -295,47 +295,173 @@ You may either upload files from your computer into your storage area, or copy t On many public servers there may be limits on disk usage. -[h2]File Attachments[/h2] +[h4]File Attachments[/h4] The quickest and easiest way to share files is through file attachments. In the row of icons below the status post editor is a tool to upload attachments. Click the tool, select a file and submit. After the file is uploaded, you will see an attachment code placed inside the text region. Do not edit this line or it may break the ability for your friends to see the attachment. You can use the post permissions dialogue box or privacy hashtags to restrict the visibility of the file - which will be set to match the permissions of the post your are sending. To delete attachments or change the permissions on the stored files, visit [observer=1][baseurl]/cloud/[observer.webname][/observer][observer=0][baseurl]/cloud/username replacing username with the nickname you provided during channel creation[/observer]. -[h2]Web Access[/h2] +[h4]Web Access[/h4] Your files are visible on the web at the location [observer=1][baseurl]/cloud/[observer.webname][/observer][observer=0][baseurl]/cloud/username[/observer] to anybody who is allowed to view them. If the viewer has sufficient privileges, they may also have the ability to create new files and folders/directories. -[h2]WebDAV access[/h2] +[h4]WebDAV access[/h4] See: [zrl=[baseurl]/help/member/member_guide#Cloud_Desktop_Clients]Cloud Desktop Clients[/zrl] -[h2]Permissions[/h2] +[h4]Permissions[/h4] When using WebDAV, the file is created with your channel's default file permissions and this cannot be changed from within the operating system. It also may not be as restrictive as you would like. What we've found is that the preferred method of making files private is to first create folders or directories; then visit [observer=1][baseurl]/cloud/[observer.webname][/observer][observer=0][baseurl]/cloud/username[/observer] select the directory and change the permissions. Do this before you put anything into the directory. The directory permissions take precedence so you can then put files or other folders into that container and they will be protected from unwanted viewers by the directory permissions. It is common for folks to create a "personal" or "private" folder which is restricted to themselves. You can use this as a personal cloud to store anything from anywhere on the web or any computer and it is protected from others. You might also create folders for "family" and "friends" with permission granted to appropriate privacy groups. -[h2]Cloud Desktop Clients[/h2] +[h4]Cloud Desktop Clients - Windows[/h4] + +RedDav using Windows 7 graphical user interface wizard: +1. Left-click the Start-button to open the start menu. +2. Right-click the My computer icon to access its menu. +3. Left-click Map network drive... to open the connection dialog wizard. +4. Type #^[url=https://example.net/dav/your_channel_name]https://example.net/dav/your_channel_name[/url] in the textbox and click the Complete button where "example.net" is the URL of your hub. +5. Type your Hubzilla account's user name. IMPORTANT - NO at-sign or domain name. +6. Type your Hubzilla password + +[h4]Cloud Desktop Clients - Linux[/h4] + +[h5]Mount as a filesystem[/h5] + +[b]Mounting As A Filesystem[/b] + +To install your cloud directory as a filesystem, you first need davfs2 installed. 99% of the time, this will be included in your distributions repositories. In Debian + +[code]apt-get install davfs2[/code] + +If you want to let normal users mount the filesystem + +[code] dpkg-reconfigure davfs2[/code] + +and select "yes" at the prompt. + +Now you need to add any user you want to be able to mount dav to the davfs2 group + +[code]usermod -aG davfs2 <DesktopUser>[/code] + +[b]Note:[/b] on some systems the user group may be different, i.e. - "network" +on Arch Linux. If in doubt, check the davfs documentation for your +particular OS. + +Edit /etc/fstab + +[code]nano /etc/fstab[/code] + + to include your cloud directory by adding + +[code] +[baseurl]/dav/ /mount/point davfs user,noauto,uid=<DesktopUser>,file_mode=600,dir_mode=700 0 1 +[/code] + +Where [baseurl] is the URL of your hub, /mount/point is the location you want to mount the cloud, and <DesktopUser> is the user you log in to one your computer. Note that if you are mounting as a normal user (not root) the mount point must be in your home directory. + +For example, if I wanted to mount my cloud to a directory called 'cloud' in my home directory, and my username was bob, my fstab would be + +[code][baseurl]/dav/ /home/bob/cloud davfs user,noauto,uid=bob,file_mode=600,dir_mode=700 0 1[/code] + +Now, create the mount point. + +[code]mkdir /home/bob/cloud[/code] + +and also create a directory file to store your credentials + +[code]mkdir /home/bob/.davfs2[/code] + +Create a file called 'secrets' + +[code]nano /home/bob/.davfs2/secrets[/code] + +and add your cloud login credentials + +[code] +[baseurl]/dav <username> <password> +[/code] -[h3]Windows Clients[/h3] -[list] -[*][zrl=[baseurl]/help/dav_windows]Windows Internal Client[/zrl] -[/list] +Where <username> and <password> are the username and password [i]for your hub[/i]. -[h3]Linux Clients[/h3] -[list] -[*][zrl=[baseurl]/help/dav_mount]Command Line as a Filesystem[/zrl] -[*][zrl=[baseurl]/help/dav_dolphin]Dolphin[/zrl] -[*][zrl=[baseurl]/help/dav_konqueror]Konqueror[/zrl] -[*][zrl=[baseurl]/help/dav_nautilus]Nautilus[/zrl] -[*][zrl=[baseurl]/help/dav_nemo]Nemo[/zrl] -[/list] +Don't let this file be writeable by anyone who doesn't need it with -[h3]Server Notes[/h3] +[code]chmod 600 /home/bob/.davfs2/secrets[/code] + +Finally, mount the drive. + +[code]mount [baseurl]/dav[/code] + +You can now find your cloud at /home/bob/cloud and use it as though it were part of your local filesystem - even if the applications you are using have no dav support themselves. + +[b]Troubleshooting[/b] + +With some webservers and certain configurations, you may find davfs2 creating files with 0 bytes file size where other clients work just fine. This is generally caused by cache and locks. If you are affected by this issue, you need to edit your davfs2 configuration. + +[code]nano /etc/davfs2/davfs2.conf[/code] + +Your distribution will provide a sample configuration, and this file should already exist, however, most of it will be commented out with a # at the beginning of the line. + +First step is to remove locks. + +Edit the use_locks line so it reads [code]use_locks 0[/code]. + +Unmount your file system, remount your file system, and try copying over a file from the command line. Note you should copy a new file, and not overwrite an old one for this test. Leave it a minute or two then do [code]ls -l -h[/code] and check the file size of your new file is still greater than 0 bytes. If it is, stop there, and do nothing else. + +If that still doesn't work, disable the cache. Note that this has a performance impact so should only be done if disabling locks didn't solve your problem. Edit the cache_size and set it to [code]cache_size 0[/code] and also set file_refresh to [code]file_refresh 0[/code]. Unmount your filesystem, remount your file system, and test it again. + +If it [i]still[/i] doesn't work, there is one more thing you can try. (This one is caused by a bug in older versions of dav2fs itself, so updating to a new version may also help). Enable weak etag dropping by setting [code]drop_weak_etags 1[/code]. Unmount and remount your filesystem to apply the changes. + + +[h5]Dolphin[/h5] +Visit webdavs://example.com/dav where "example.com" is the URL of your hub. + +When prompted for a username and password, enter your channel name (the first part of your webbie - no @ or domain name) and password for your normal account. + +Note, if you are already logged in to the web interface via Konqueror, you will not be prompted for further authentication. + +[h5]Konqueror[/h5] + +Simply visit webdavs://example.com/dav after logging in to your hub, where "example.com" is the URL of your hub. + +No further authentication is required if you are logged in to your hub in the normal manner. + +Additionally, if one has authenticated at a different hub during their normal browser session, your identity will be passed to the cloud for these hubs too - meaning you can access any private files on any server, as long as you have permissions to see them, as long as you have visited that site earlier in your session. + +This functionality is normally restricted to the web interface, and is not available to any desktop software other than KDE. + +[h5]Nautilus[/h5] + +1. Open a File browsing window (that's Nautilus) +2. Select File > Connect to server from the menu +3. Type davs://<domain_name>/dav/<your_channelname> and click Connect +4. You will be prompted for your channel name (same as above) and password +5. Your personal DAV directory will be shown in the window + +[h5]Nemo[/h5] + +For (file browser) Nemo 1.8.2 under Linux Mint 15, Cinnamon 1.8.8. Nemo ist the standard file browser there. + +1st way +type "davs://<domain_name>/dav/<your_channelname>" in the address bar. + +2nd way +Menu > file > connect to server +Fill the dialog +- Server: hubzilla_domain_name +- Type: Secure WebDAV (https) +- Folder: /dav +- Username: yourchannelname +- Password: yourpassword + +Once open you can set a bookmark. + +[h5]Server Notes[/h5] Note: There have been reported issues with clients that use "chunked transfer encoding", which includes Apple iOS services, and also the "AnyClient" and "CyberDuck" tools. These work fine for downloads, but uploads often end up with files of zero size. This is caused by an incorrect implemention of chunked encoding in some current FCGI (fast-cgi) implementations. Apache running with PHP as a module does not have these issues, but when running under FCGI you may need to use alternative clients or use the web uploader. At the time of this writing the issue has been open and no updates provided for at least a year. If you encounter zero size files with other clients, please check the client notes; as there are occasional configuration issues which can also produce these symptoms. -[h1]Remove Channel or Account[/h1] +[h3]Remove Channel or Account[/h3] -[h2]Remove Channel[/h2] +[h4]Remove Channel[/h4] Go to the bottom of your channel settings page or visit the URL: @@ -343,11 +469,11 @@ Go to the bottom of your channel settings page or visit the URL: You will need to confirm your password and the channel you are currently logged into will be removed. -This is irreversible. +[hl][i][b]This is irreversible.[/b][/i][/hl] If you have identity clones on other hubs this only removes by default the channel instance which exists on this hub. -[h2]Remove Account[/h2] +[h4]Remove Account[/h4] Go to the bottom of your account settings page or visit the URL: @@ -355,8 +481,6 @@ Go to the bottom of your account settings page or visit the URL: You will need to confirm your password and the account you are currently logged into will be removed. -This is irreversible. +[hl][i][b]This is irreversible.[/b][/i][/hl] All your channels will be deleted. If you have identity clones on other hubs this only removes by default the channels instances which exists on this hub. - -#include doc/macros/main_footer.bb; diff --git a/doc/toc.html b/doc/toc.html index 458f6ec84..597a2c2c5 100644 --- a/doc/toc.html +++ b/doc/toc.html @@ -108,7 +108,7 @@ if(pageName === linkName) { var tocUl = $(this).closest('li').append('<ul>').find('ul'); tocUl.removeClass(); // Classes are automatically added to <ul> elements by something else - tocUl.toc({content: "#doco-content", headings: "h1"}); + tocUl.toc({content: "#doco-content", headings: "h3"}); tocUl.addClass('toc-content sub-menu'); tocUl.attr('id', 'doco-side-toc'); diff --git a/doc/tutorials/personal_channel.html b/doc/tutorials/personal_channel.html index 3b1fe40ba..f2ad87077 100644 --- a/doc/tutorials/personal_channel.html +++ b/doc/tutorials/personal_channel.html @@ -3,7 +3,7 @@ channel for the first time. It introduces some of the tools and features related to a personal channel in a natural way.</p> -<h1 id="Create_a_new_channel">Create a new channel</h1> +<h3 id="Create_a_new_channel">Create a new channel</h3> <p>When you log in for the first time after registering, you must create a channel. (Alternatively you can load https://grid.reticu.li/new_channel)</p> @@ -15,7 +15,7 @@ Typically if this is a personal channel that represents you, select a <strong>So with a level of default privacy that you are comfortable with. If you are unsure, select <strong>Social - Restricted</strong>.</p> -<h1 id="Configure_your_channel_features">Configure your channel features</h1> +<h3 id="Configure_your_channel_features">Configure your channel features</h3> <p>When your new channel is created you are directed to the channel settings page. Take the time to look around at all the settings pages to familiarize yourself with @@ -27,7 +27,7 @@ your selections.</p> <p><img class="img-responsive" src="/help/tutorials/assets/3656a67dce40a1fc2515e9089217f2e136d4fcf8babe77bac00ecaad43ce.png" alt="image"><img class="img-responsive" src="/help/tutorials/assets/4aaaf1e124514c8d6999a5fe1d07be5af460cda4ba6cde9106ebc1564bb0.png" alt="image"><img class="img-responsive" src="/help/tutorials/assets/99a6efda4df631dfb2d2a849412044cc6a0f8aebeac289d28786f2649d24.png" alt="image"><img class="img-responsive" src="/help/tutorials/assets/e5d5674a34e848e2cce90a60fc416415271d9c51b81ad2a950fb0157222a.png" alt="image"></p> -<h1 id="Add_a_profile_photo">Add a profile photo</h1> +<h3 id="Add_a_profile_photo">Add a profile photo</h3> <p>Navigate to your channel home by clicking the "Home" icon on the left side of the navbar, and then select the <strong>About</strong> tab to view your profile.</p> @@ -54,7 +54,7 @@ profile pic has been automatically posted.</p> <p><img class="img-responsive" src="/help/tutorials/assets/1ebe02c205962dd25035c441631745d16acdb7a44e50d148256c8ad26a67.png" alt="image"></p> -<h1 id="Compose_a_post">Compose a post</h1> +<h3 id="Compose_a_post">Compose a post</h3> <p>Go to your channel home and open the post editor by pressing the <strong>Share</strong> textbox at the top of the channel "wall". Enter a message, and then drag-and-drop an image @@ -73,7 +73,7 @@ so you can specify exactly who can access this post.</p> <p><img class="img-responsive" src="/help/tutorials/assets/2b539d5a8474d6ec6dc91155b628d9be5f99ab04a78108ec404f53ec7bb5.png" alt="image"></p> -<h1 id="Use_an_uploaded_image_as_a_channel_cover_photo">Use an uploaded image as a channel cover photo</h1> +<h3 id="Use_an_uploaded_image_as_a_channel_cover_photo">Use an uploaded image as a channel cover photo</h3> <p>One way to add some pizzazz your channel is to add a cover photo that visitors will see when they load your channel page. Hubzilla's integrated cloud file system @@ -97,7 +97,7 @@ channel page will fade in as you scroll down.</p> <p><img class="img-responsive" src="/help/tutorials/assets/4cf326152797a8ecdf5630e921756f825ee00f8ee464d3ef9fed971d2852.png" alt="image"></p> -<h1 id="Make_a_connection">Make a connection</h1> +<h3 id="Make_a_connection">Make a connection</h3> <p>Making connections between channels to share things is what Hubzilla is all about. Making a connection is simple. If you do not already know how to reach a channel's home diff --git a/view/tpl/help.tpl b/view/tpl/help.tpl index 8eb53417a..15d8548a3 100644 --- a/view/tpl/help.tpl +++ b/view/tpl/help.tpl @@ -3,10 +3,10 @@ <h2>{{$title}}: {{$heading}}</h2> </div> <div class="section-content-wrapper" id="doco-content"> - <h1 class="fakelink" id="doco-top-toc-heading"><span onclick="docoTocToggle(); return false;"> + <h3 class="fakelink" id="doco-top-toc-heading"><span onclick="docoTocToggle(); return false;"> <i class="fakelink fa fa-caret-right" id="doco-toc-toggle"></i> {{$tocHeading}} - </span></h1> + </span></h3> <ul id="doco-top-toc" style="margin-bottom: 1.5em; display: none;"></ul> {{$content}} </div> @@ -16,7 +16,7 @@ // Generate the table of contents in the side nav menu (see view/tpl/help.tpl) $(document).ready(function () { - $('#doco-top-toc').toc({content: "#doco-content", headings: "h1,h2,h3,h4"}); + $('#doco-top-toc').toc({content: "#doco-content", headings: "h3,h4,h5,h6"}); }); function docoTocToggle() { |