diff options
| -rw-r--r-- | doc/admin/administrator_guide.html | 342 | ||||
| -rw-r--r-- | doc/admin/administrator_guide.md | 345 | ||||
| -rw-r--r-- | doc/developer/developer_guide.html | 470 | ||||
| -rw-r--r-- | doc/developer/developer_guide.md | 422 | ||||
| -rw-r--r-- | doc/member/member_faq.bb | 10 | ||||
| -rw-r--r-- | doc/member/member_faq.html | 19 | ||||
| -rw-r--r-- | doc/member/member_guide.bb | 362 | ||||
| -rw-r--r-- | doc/member/member_guide.html | 460 |
8 files changed, 1139 insertions, 1291 deletions
diff --git a/doc/admin/administrator_guide.html b/doc/admin/administrator_guide.html deleted file mode 100644 index 674d2a916..000000000 --- a/doc/admin/administrator_guide.html +++ /dev/null @@ -1,342 +0,0 @@ -<h1 id="Overview">Overview</h1> - -<p>Hubzilla is more than a simple web application. It is a -complex communications system which more closely resembles an email server -than a web server. For reliability and performance, messages are delivered in -the background and are queued for later delivery when sites are down. This -kind of functionality requires a bit more of the host system than the typical -blog. Not every PHP/MySQL hosting provider will be able to support -Hubzilla. Many will but please review the requirements and confirm these -with your hosting provider prior to installation.</p> - -<p>We've tried very hard to ensure that Hubzilla will run on commodity -hosting platforms such as those used to host Wordpress blogs and Drupal -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.</p> - -<h1 id="Where_to_find_more_help">Where to find more help</h1> - -<p>If you encounter problems or have issues not addressed in this documentation, -please let us know via the <a href="https://github.com/redmatrix/hubzilla/issues">Github issue -tracker</a>. Please be as clear as you -can about your operating environment and provide as much detail as possible -about any error messages you may see, so that we can prevent it from happening -in the future. Due to the large variety of operating systems and PHP platforms -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.</p> - -<h1 id="Before_you_begin">Before you begin</h1> - -<h2 id="Choose_a_domain_name_or_subdomain_name_for_your_server">Choose a domain name or subdomain name for your server</h2> - -<p>Hubzilla can only be installed into the root of a domain or sub-domain, and can -not be installed using alternate TCP ports.</p> - -<h2 id="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</h2> - -<p>You SHOULD use SSL. If you use SSL, you MUST use a "browser-valid" certificate.<br><em>You MUST NOT use self-signed certificates!</em></p> - -<p>Please test your certificate prior to installation. A web tool for testing your -certificate is available at "http://www.digicert.com/help/". When visiting your -site for the first time, please use the SSL ("https://") URL if SSL is available. -This will avoid problems later. The installation routine will not allow you to -use a non browser-valid certificate.</p> - -<p>This restriction is incorporated because public posts from you may contain -references to images on your own hub. Other members viewing their stream on -other hubs will get warnings if your certificate is not trusted by their web -browser. This will confuse many people because this is a decentralised network -and they will get the warning about your hub while viewing their own hub and may -think their own hub has an issue. These warnings are very technical and scary to -some folks, many of whom will not know how to proceed except to follow the browser -advice. This is disruptive to the community. That said, we recognise the issues -surrounding the current certificate infrastructure and agree there are many -problems, but that doesn't change the requirement.</p> - -<p>Free "browser-valid" certificates are available from providers such as StartSSL -and LetsEncrypt.</p> - -<p>If you do NOT use SSL, there may be a delay of up to a minute for the initial -install script * while we check the SSL port to see if anything responds there. -When communicating with new sites, Hubzilla always attempts connection on the -SSL port first, before falling back to a less secure connection. If you do not -use SSL, your webserver MUST NOT listen on port 443 at all.</p> - -<p>If you use LetsEncrypt to provide certificates and create a file under -.well-known/acme-challenge so that LetsEncrypt can verify your domain ownership, -please remove or rename the .well-known directory as soon as the certificate is -generated. Hubzilla will provide its own handler for ".well-known" services when -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.</p> - -<h1 id="Deployment">Deployment</h1> - -<p>There are several ways to deploy a new hub.</p> - -<ul><li>Manual installation on an existing server</li> -<li>Automated installation on an existing server using a shell script</li> -<li>Automated deployment using an OpenShift virtual private server (VPS)</li> -</ul><h1 id="Requirements">Requirements</h1> - -<ul><li><p>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. -Apache and nginx have the most support.</p></li> -<li><p>PHP 5.5 or later.</p> - -<ul><li>Note that on some shared hosting environments, the <em>command line</em> version of -PHP might differ from the <em>webserver</em> version</li> -</ul></li> -<li><p>PHP <em>command line</em> access with register_argc_argv set to true in the -php.ini file * and with no hosting provider restrictions on the use of -exec() and proc_open().</p></li> -<li><p>curl, gd (with at least jpeg and png support), mysqli, mbstring, mcrypt, -and openssl extensions. The imagick extension is not required but desirable.</p></li> -<li><p>xml extension is required if you want webdav to work.</p></li> -<li><p>some form of email server or email gateway such that PHP mail() works.</p></li> -<li><p>Mysql 5.x or MariaDB or postgres database server.</p></li> -<li><p>ability to schedule jobs with cron.</p></li> -<li><p>Installation into a top-level domain or sub-domain (without a -directory/path component in the URL) is REQUIRED.</p></li> -</ul><h1 id="Manual_Installation">Manual Installation</h1> - -<h2 id="Unpack_the_Hubzilla_files_into_the_root_of_your_web_server_document_area">Unpack the Hubzilla files into the root of your web server document area</h2> - -<p>If you copy the directory tree to your webserver, make sure that you include the -hidden files like .htaccess.</p> - -<p>If you are able to do so, we recommend using git to clone the source -repository rather than to use a packaged tar or zip file. This makes the -software much easier to update. The Linux command to clone the repository -into a directory "mywebsite" would be:</p> - -<pre><code>git clone https://github.com/redmatrix/hubzilla.git mywebsite -</code></pre> - -<p>and then you can pick up the latest changes at any time with:</p> - -<pre><code>git pull -</code></pre> - -<p>make sure folders <code class="inline-code">store/[data]/smarty3</code> and <code class="inline-code">store</code> exist and are -writable by the webserver:</p> - -<pre><code>mkdir -p "store/[data]/smarty3" -chmod -R 777 store - -This permission (777) is very dangerous and if you have sufficient -privilege and knowledge you should make these directories writeable -only by the webserver and, if different, the user that will run the -cron job (see below). In many shared hosting environments this may be -difficult without opening a trouble ticket with your provider. The -above permissions will allow the software to work, but are not -optimal. -</code></pre> - -<p>The following directories also need to be writable by the webserver in order for certain -web-based administrative tools to function:</p> - -<ul><li><code class="inline-code">addon</code></li> -<li><code class="inline-code">extend</code></li> -<li><code class="inline-code">view/theme</code></li> -<li><code class="inline-code">widget</code></li> -</ul><h2 id="Official_addons">Official addons</h2> - -<h3 id="Installation">Installation</h3> - -<p>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::</p> - -<pre><code>cd mywebsite -util/add_addon_repo https://github.com/redmatrix/hubzilla-addons.git hzaddons -</code></pre> - -<h3 id="Updating">Updating</h3> - -<p>For keeping the addon tree updated, you should be on your top level website directory and issue an update command for that repository::</p> - -<pre><code>cd mywebsite -util/update_addon_repo hzaddons -</code></pre> - -<p>Create searchable representations of the online documentation. You may do this - any time that the documentation is updated :</p> - -<pre><code>cd mywebsite -util/importdoc -</code></pre> - -<h1 id="Automated_installation_via_the_homeinstall_shell_script">Automated installation via the .homeinstall shell script</h1> - -<p>There is a shell script in (<code class="inline-code">.homeinstall/hubzilla-setup.sh</code>) that will install Hubzilla 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.</p> - -<h2 id="Requirements">Requirements</h2> - -<p>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:</p> - -<ul><li><p>Home-PC (Debian-8.3.0-amd64)</p> - -<ul><li>Internet connection and router at home</li> -<li>Mini-pc connected to your router</li> -<li>USB drive for backups</li> -<li>Fresh installation of Debian on your mini-pc</li> -<li>Router with open ports 80 and 443 for your Debian</li> -</ul></li> -<li><p>DigitalOcean droplet (Debian 8.3 x64 / 512 MB Memory / 20 GB Disk / NYC3)</p></li> -</ul><h2 id="Overview_of_installation_steps">Overview of installation steps</h2> - -<ol><li><code class="inline-code">apt-get install git</code></li> -<li><code class="inline-code">mkdir -p /var/www/html</code></li> -<li><code class="inline-code">cd /var/www/html</code></li> -<li><code class="inline-code">git clone https://github.com/redmatrix/hubzilla.git .</code></li> -<li><code class="inline-code">nano .homeinstall/hubzilla-config.txt</code></li> -<li><code class="inline-code">cd .homeinstall/</code></li> -<li><code class="inline-code">./hubzilla-setup.sh</code></li> -<li><code class="inline-code">sed -i "s/^upload_max_filesize =.*/upload_max_filesize = 100M/g" /etc/php5/apache2/php.ini</code></li> -<li><code class="inline-code">sed -i "s/^post_max_size =.*/post_max_size = 100M/g" /etc/php5/apache2/php.ini</code></li> -<li><code class="inline-code">service apache2 reload</code></li> -<li>Open your domain with a browser and step throught the initial configuration of Hubzilla.</li> -</ol><h1 id="Service_Classes">Service Classes</h1> - -<p>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 -classes according to your needs in the <code class="inline-code">.htconfig.php</code> file. For example, create -a <em>standard</em> and <em>premium</em> class using the following lines:</p> - -<pre><code>// Service classes - -App::$config['system']['default_service_class']='standard'; // this is the default service class that is attached to every new account - -// configuration for parent service class -App::$config['service_class']['standard'] = -array('photo_upload_limit'=>2097152, // total photo storage limit per channel (here 2MB) -'total_identities' =>1, // number of channels an account can create -'total_items' =>0, // number of top level posts a channel can create. Applies only to top level posts of the channel user, other posts and comments are unaffected -'total_pages' =>100, // number of pages a channel can create -'total_channels' =>100, // number of channels the user can add, other users can still add this channel, even if the limit is reached -'attach_upload_limit' =>2097152, // total attachment storage limit per channel (here 2MB) -'chatters_inroom' =>20); - -// configuration for teacher service class -App::$config['service_class']['premium'] = -array('photo_upload_limit'=>20000000000, // total photo storage limit per channel (here 20GB) -'total_identities' =>20, // number of channels an account can create -'total_items' =>20000, // number of top level posts a channel can create. Applies only to top level posts of the channel user, other posts and comments are unaffected -'total_pages' =>400, // number of pages a channel can create -'total_channels' =>2000, // number of channels the user can add, other users can still add this channel, even if the limit is reached -'attach_upload_limit' =>20000000000, // total attachment storage limit per channel (here 20GB) -'chatters_inroom' =>100); -</code></pre> - -<p>To apply a service class to an existing account, use the command line utility from the -web root:</p> - -<p><code class="inline-code">util/service_class</code> -list service classes</p> - -<p><code class="inline-code">util/config system default_service_class firstclass</code> -set the default service class to 'firstclass'</p> - -<p><code class="inline-code">util/service_class firstclass</code> -list the services that are part of 'firstclass' service class</p> - -<p><code class="inline-code">util/service_class firstclass photo_upload_limit 10000000</code> -set firstclass total photo disk usage to 10 million bytes</p> - -<p><code class="inline-code">util/service_class --account=5 firstclass</code> -set account id 5 to service class 'firstclass' (with confirmation)</p> - -<p><code class="inline-code">util/service_class --channel=blogchan firstclass</code> -set the account that owns channel 'blogchan' to service class 'firstclass' (with confirmation)</p> - -<p><strong>Service class limit options</strong></p> - -<ul><li>photo_upload_limit - maximum total bytes for photos</li> -<li>total_items - maximum total toplevel posts</li> -<li>total_pages - maximum comanche pages</li> -<li>total_identities - maximum number of channels owned by account</li> -<li>total_channels - maximum number of connections</li> -<li>total_feeds - maximum number of rss feed connections</li> -<li>attach_upload_limit - maximum file upload storage (bytes)</li> -<li>minimum_feedcheck_minutes - lowest setting allowed for polling rss feeds</li> -<li>chatrooms - maximum chatrooms</li> -<li>chatters_inroom - maximum chatters per room</li> -<li>access_tokens - maximum number of Guest Access Tokens per channel</li> -</ul><h1 id="Theme_management">Theme management</h1> - -<h2 id="Repo_management_example">Repo management example</h2> - -<ol><li><p>Navigate to your hub web root</p> - -<p><code class="inline-code">root@hub:/root# cd /var/www</code></p></li> -<li><p>Add the theme repo and give it a name</p> - -<p><code class="inline-code">root@hub:/var/www# util/add_theme_repo https://github.com/DeadSuperHero/redmatrix-themes.git DeadSuperHero</code></p></li> -<li><p>Update the repo by using</p> - -<p><code class="inline-code">root@hub:/var/www# util/update_theme_repo DeadSuperHero</code></p></li> -</ol><h1 id="Channel_Directory">Channel Directory</h1> - -<h2 id="Keywords">Keywords</h2> - -<p>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 -can use the <em>config</em> tool:</p> - -<pre><code>util/config system disable_directory_keywords 1 -</code></pre> - -<p>If your hub is in the standalone mode because you do not wish to connect to the -global grid, you may instead ensure the the <em>directory_server</em> system option is -empty:</p> - -<pre><code>util/config system directory_server "" -</code></pre> - -<h1 id="Upgrading_from_RedMatrix_to_Hubzilla">Upgrading from RedMatrix to Hubzilla</h1> - -<h2 id="How_to_migrate_an_individual_channel_from_RedMatrix_to_Hubzilla">How to migrate an individual channel from RedMatrix to Hubzilla</h2> - -<ol><li>Clone the channel by opening an account on a Hubzilla hub and performing a basic import (not content) from the original RedMatrix hub. Give your new clone time to sync connections and settings.</li> -<li>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.</li> -<li>Import the JSON data files sequentially in chronological order into the Hubzilla clone using the new.hub/import_items tool.</li> -<li>Inform your Friendica and Diaspora contacts that your channel moves. They need to reconnect to your new address. </li> -<li>After successful import (check!) delete your channel on the old RedMatrix Server.</li> -<li>On the Hubzilla 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.</li> -</ol><h1 id="Troubleshooting">Troubleshooting</h1> - -<h2 id="Log_files">Log files</h2> - -<p><a href="https://macgirvin.com/display/044c72684b95c46a77ac7560656d1dc38504244dc649626c637193f6dd7c7dc4@macgirvin.com">Allow me to elaborate on logfiles...</a></p> - -<p>There are three different log facilities.</p> - -<p><strong>The first is the database failure log</strong>. This is only used if you create a file called specifically 'dbfail.out' in the root folder of your website and make it write-able by the web server. If we have any database failed queries, they are all reported here. They generally indicate typos in our queries, but also occur if the database server disconnects or tables get corrupted. On rare occasions we'll see race conditions in here where two processes tried to create an xchan or cache entry with the same ID. Any other errors (especially persistent errors) should be investigated.</p> - -<p><strong>The second is the PHP error log</strong>. This is created by the language processor and only reports issues in the language environment. Again these can be syntax errors or programming errors, but these generally are fatal and result in a "white screen of death"; e.g. PHP terminates. You should probably look at this file if something goes wrong that doesn't result in a white screen of death, but it isn't uncommon for this file to be empty for days on end.</p> - -<p>There are some lines at the bottom of the supplied .htconfig.php file; which if uncommented will enable a PHP error log (<em>extremely</em> useful for finding the source of white screen failures). This isn't done by default due to potential issues with logfile ownership and write permissions and the fact that there is no logfile rotation by default.</p> - -<p><strong>The third is the "application log"</strong>. This is used by Hubzilla to report what is going on in the program and usually reports any difficulties or unexpected data we received. It also occasionally reports "heartbeat" status messages to indicate that we reached a certain point in a script. <strong>This</strong> is the most important log file to us, as we create it ourself for the sole purpose of reporting the status of background tasks and anything that seems weird or out of place. It may not be fatal, but maybe just unexpected. If you're performing a task and there's a problem, let us know what is in this file when the problem occurred. (Please don't send me 100M dumps you'll only piss me off). Just a few relevant lines so I can rule out a few hundred thousand lines of code and concentrate on where the problem starts showing up.</p> - -<p>These are your site logs, not mine. We report serious issues at any log level. I highly recommend 'DEBUG' log level for most sites - which provides a bit of additional info and doesn't create huge logfiles. When there's a problem which defies all attempts to track, you might wish to use DATA log level for a short period of time to capture all the detail of what structures we were dealing with at the time. This log level will use a lot of space so is recommended only for brief periods or for developer test sites.</p> - -<p>I recommend configuring logrotate for both the php log and the application log. I usually have a look at dbfail.out every week or two, fix any issues reported and then starting over with a fresh file. Likewise with the PHP logfile. I refer to it once in a while to see if there's something that needs fixing.</p> - -<p>If something goes wrong, and it's not a fatal error, I look at the application logfile. Often I will -<code class="inline-code">tail -f logfile.out</code></p> - -<p>While repeating an operation that has problems. Often I'll insert extra logging statements in the code if there isn't any hint what's going wrong. Even something as simple as "got here" or printing out the value of a variable that might be suspect. You can do this too - in fact I encourage you to do so. Once you've found what you need to find, you can</p> - -<p><code class="inline-code">git checkout file.php</code></p> - -<p>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.</p> - -<h3 id="Rotating_log_files">Rotating log files</h3> - -<ol><li>Enable the <strong>logrot</strong> addon in the official <a href="https://github.com/redmatrix/hubzilla-addons">hubzilla-addons</a> repo</li> -<li>Create a directory in your web root called <code class="inline-code">log</code> with webserver write permissions</li> -<li>Go to the <strong>logrot</strong> admin settings and enter this folder name as well as the max size and number of retained log files.</li> -</ol>
\ No newline at end of file diff --git a/doc/admin/administrator_guide.md b/doc/admin/administrator_guide.md new file mode 100644 index 000000000..47592b58c --- /dev/null +++ b/doc/admin/administrator_guide.md @@ -0,0 +1,345 @@ + +# Overview + +Hubzilla is more than a simple web application. It is a +complex communications system which more closely resembles an email server +than a web server. For reliability and performance, messages are delivered in +the background and are queued for later delivery when sites are down. This +kind of functionality requires a bit more of the host system than the typical +blog. Not every PHP/MySQL hosting provider will be able to support +Hubzilla. Many will but please review the requirements and confirm these +with your hosting provider prior to installation. + +We've tried very hard to ensure that Hubzilla will run on commodity +hosting platforms such as those used to host Wordpress blogs and Drupal +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 +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 +can about your operating environment and provide as much detail as possible +about any error messages you may see, so that we can prevent it from happening +in the future. Due to the large variety of operating systems and PHP platforms +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 + +## Choose a domain name or subdomain name for your server + +Hubzilla 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 + +You SHOULD use SSL. If you use SSL, you MUST use a "browser-valid" certificate. +*You MUST NOT use self-signed certificates!* + +Please test your certificate prior to installation. A web tool for testing your +certificate is available at "http://www.digicert.com/help/". When visiting your +site for the first time, please use the SSL ("https://") URL if SSL is available. +This will avoid problems later. The installation routine will not allow you to +use a non browser-valid certificate. + + +This restriction is incorporated because public posts from you may contain +references to images on your own hub. Other members viewing their stream on +other hubs will get warnings if your certificate is not trusted by their web +browser. This will confuse many people because this is a decentralised network +and they will get the warning about your hub while viewing their own hub and may +think their own hub has an issue. These warnings are very technical and scary to +some folks, many of whom will not know how to proceed except to follow the browser +advice. This is disruptive to the community. That said, we recognise the issues +surrounding the current certificate infrastructure and agree there are many +problems, but that doesn't change the requirement. + +Free "browser-valid" certificates are available from providers such as StartSSL +and LetsEncrypt. + +If you do NOT use SSL, there may be a delay of up to a minute for the initial +install script * while we check the SSL port to see if anything responds there. +When communicating with new sites, Hubzilla always attempts connection on the +SSL port first, before falling back to a less secure connection. If you do not +use SSL, your webserver MUST NOT listen on port 443 at all. + +If you use LetsEncrypt to provide certificates and create a file under +.well-known/acme-challenge so that LetsEncrypt can verify your domain ownership, +please remove or rename the .well-known directory as soon as the certificate is +generated. Hubzilla will provide its own handler for ".well-known" services when +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 +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 +* 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. + Apache and nginx have the most support. + +* PHP 5.5 or later. + * Note that on some shared hosting environments, the _command line_ version of +PHP might differ from the _webserver_ version + +* PHP *command line* access with register_argc_argv set to true in the + php.ini file * and with no hosting provider restrictions on the use of + exec() and proc_open(). + +* curl, gd (with at least jpeg and png support), mysqli, mbstring, mcrypt, + and openssl extensions. The imagick extension is not required but desirable. + +* xml extension is required if you want webdav to work. + +* some form of email server or email gateway such that PHP mail() works. + +* Mysql 5.x or MariaDB or postgres database server. + +* ability to schedule jobs with cron. + +* Installation into a top-level domain or sub-domain (without a + directory/path component in the URL) is REQUIRED. + +# Manual Installation # + +## Unpack the Hubzilla 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. + +If you are able to do so, we recommend using git to clone the source +repository rather than to use a packaged tar or zip file. This makes the +software much easier to update. The Linux command to clone the repository +into a directory "mywebsite" would be: + + git clone https://github.com/redmatrix/hubzilla.git mywebsite + +and then you can pick up the latest changes at any time with: + + git pull + +make sure folders ``store/[data]/smarty3`` and ``store`` exist and are +writable by the webserver: + + mkdir -p "store/[data]/smarty3" + chmod -R 777 store + + This permission (777) is very dangerous and if you have sufficient + privilege and knowledge you should make these directories writeable + only by the webserver and, if different, the user that will run the + cron job (see below). In many shared hosting environments this may be + difficult without opening a trouble ticket with your provider. The + above permissions will allow the software to work, but are not + optimal. + +The following directories also need to be writable by the webserver in order for certain +web-based administrative tools to function: + +* `addon` +* `extend` +* `view/theme` +* `widget` + +## 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 +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 + util/update_addon_repo hzaddons + +Create searchable representations of the online documentation. You may do this + any time that the documentation is updated : + + cd mywebsite + util/importdoc + +# Automated installation via the .homeinstall shell script +There is a shell script in (``.homeinstall/hubzilla-setup.sh``) that will install Hubzilla 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 +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) + + * Internet connection and router at home + * Mini-pc connected to your router + * USB drive for backups + * Fresh installation of Debian on your mini-pc + * Router with open ports 80 and 443 for your Debian + +* DigitalOcean droplet (Debian 8.3 x64 / 512 MB Memory / 20 GB Disk / NYC3) + +## Overview of installation steps +1. `apt-get install git` +1. `mkdir -p /var/www/html` +1. `cd /var/www/html` +1. `git clone https://github.com/redmatrix/hubzilla.git .` +1. `nano .homeinstall/hubzilla-config.txt` +1. `cd .homeinstall/` +1. `./hubzilla-setup.sh` +1. `sed -i "s/^upload_max_filesize =.*/upload_max_filesize = 100M/g" /etc/php5/apache2/php.ini` +1. `sed -i "s/^post_max_size =.*/post_max_size = 100M/g" /etc/php5/apache2/php.ini` +1. `service apache2 reload` +1. Open your domain with a browser and step throught the initial configuration of Hubzilla. + +# 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 +classes according to your needs in the `.htconfig.php` file. For example, create +a _standard_ and _premium_ class using the following lines: + + // Service classes + + App::$config['system']['default_service_class']='standard'; // this is the default service class that is attached to every new account + + // configuration for parent service class + App::$config['service_class']['standard'] = + array('photo_upload_limit'=>2097152, // total photo storage limit per channel (here 2MB) + 'total_identities' =>1, // number of channels an account can create + 'total_items' =>0, // number of top level posts a channel can create. Applies only to top level posts of the channel user, other posts and comments are unaffected + 'total_pages' =>100, // number of pages a channel can create + 'total_channels' =>100, // number of channels the user can add, other users can still add this channel, even if the limit is reached + 'attach_upload_limit' =>2097152, // total attachment storage limit per channel (here 2MB) + 'chatters_inroom' =>20); + + // configuration for teacher service class + App::$config['service_class']['premium'] = + array('photo_upload_limit'=>20000000000, // total photo storage limit per channel (here 20GB) + 'total_identities' =>20, // number of channels an account can create + 'total_items' =>20000, // number of top level posts a channel can create. Applies only to top level posts of the channel user, other posts and comments are unaffected + 'total_pages' =>400, // number of pages a channel can create + 'total_channels' =>2000, // number of channels the user can add, other users can still add this channel, even if the limit is reached + 'attach_upload_limit' =>20000000000, // total attachment storage limit per channel (here 20GB) + 'chatters_inroom' =>100); + +To apply a service class to an existing account, use the command line utility from the +web root: + +`util/service_class` +list service classes + +`util/config system default_service_class firstclass` +set the default service class to 'firstclass' + +`util/service_class firstclass` +list the services that are part of 'firstclass' service class + +`util/service_class firstclass photo_upload_limit 10000000` +set firstclass total photo disk usage to 10 million bytes + +`util/service_class --account=5 firstclass` +set account id 5 to service class 'firstclass' (with confirmation) + +`util/service_class --channel=blogchan firstclass` +set the account that owns channel 'blogchan' to service class 'firstclass' (with confirmation) + +**Service class limit options** + +* photo_upload_limit - maximum total bytes for photos +* total_items - maximum total toplevel posts +* total_pages - maximum comanche pages +* total_identities - maximum number of channels owned by account +* total_channels - maximum number of connections +* total_feeds - maximum number of rss feed connections +* attach_upload_limit - maximum file upload storage (bytes) +* minimum_feedcheck_minutes - lowest setting allowed for polling rss feeds +* chatrooms - maximum chatrooms +* chatters_inroom - maximum chatters per room +* access_tokens - maximum number of Guest Access Tokens per channel + +# Theme management +## Repo management example +1. Navigate to your hub web root + + ``` + root@hub:/root# cd /var/www + ``` +2. Add the theme repo and give it a name + + ``` + root@hub:/var/www# util/add_theme_repo https://github.com/DeadSuperHero/redmatrix-themes.git DeadSuperHero + ``` +3. Update the repo by using + + ``` + root@hub:/var/www# util/update_theme_repo DeadSuperHero + ``` + +# Channel Directory + +## 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 +can use the *config* tool: + + util/config system disable_directory_keywords 1 + +If your hub is in the standalone mode because you do not wish to connect to the +global grid, you may instead ensure the the _directory_server_ system option is +empty: + + util/config system directory_server "" + +# Upgrading from RedMatrix to Hubzilla + +## How to migrate an individual channel from RedMatrix to Hubzilla + +1. Clone the channel by opening an account on a Hubzilla 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. +1. Import the JSON data files sequentially in chronological order into the Hubzilla clone using the new.hub/import_items tool. +1. Inform your Friendica and Diaspora contacts that your channel moves. They need to reconnect to your new address. +1. After successful import (check!) delete your channel on the old RedMatrix Server. +1. On the Hubzilla 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 + +There are three different log facilities. + +**The first is the database failure log**. This is only used if you create a file called specifically 'dbfail.out' in the root folder of your website and make it write-able by the web server. If we have any database failed queries, they are all reported here. They generally indicate typos in our queries, but also occur if the database server disconnects or tables get corrupted. On rare occasions we'll see race conditions in here where two processes tried to create an xchan or cache entry with the same ID. Any other errors (especially persistent errors) should be investigated. + +**The second is the PHP error log**. This is created by the language processor and only reports issues in the language environment. Again these can be syntax errors or programming errors, but these generally are fatal and result in a "white screen of death"; e.g. PHP terminates. You should probably look at this file if something goes wrong that doesn't result in a white screen of death, but it isn't uncommon for this file to be empty for days on end. + +There are some lines at the bottom of the supplied .htconfig.php file; which if uncommented will enable a PHP error log (*extremely* useful for finding the source of white screen failures). This isn't done by default due to potential issues with logfile ownership and write permissions and the fact that there is no logfile rotation by default. + + +**The third is the "application log"**. This is used by Hubzilla to report what is going on in the program and usually reports any difficulties or unexpected data we received. It also occasionally reports "heartbeat" status messages to indicate that we reached a certain point in a script. **This** is the most important log file to us, as we create it ourself for the sole purpose of reporting the status of background tasks and anything that seems weird or out of place. It may not be fatal, but maybe just unexpected. If you're performing a task and there's a problem, let us know what is in this file when the problem occurred. (Please don't send me 100M dumps you'll only piss me off). Just a few relevant lines so I can rule out a few hundred thousand lines of code and concentrate on where the problem starts showing up. + +These are your site logs, not mine. We report serious issues at any log level. I highly recommend 'DEBUG' log level for most sites - which provides a bit of additional info and doesn't create huge logfiles. When there's a problem which defies all attempts to track, you might wish to use DATA log level for a short period of time to capture all the detail of what structures we were dealing with at the time. This log level will use a lot of space so is recommended only for brief periods or for developer test sites. + +I recommend configuring logrotate for both the php log and the application log. I usually have a look at dbfail.out every week or two, fix any issues reported and then starting over with a fresh file. Likewise with the PHP logfile. I refer to it once in a while to see if there's something that needs fixing. + +If something goes wrong, and it's not a fatal error, I look at the application logfile. Often I will +``` +tail -f logfile.out +``` + +While repeating an operation that has problems. Often I'll insert extra logging statements in the code if there isn't any hint what's going wrong. Even something as simple as "got here" or printing out the value of a variable that might be suspect. You can do this too - in fact I encourage you to do so. Once you've found what you need to find, you can + +``` +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 + +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 +1. Go to the **logrot** admin settings and enter this folder name as well as the max size and number of retained log files.
\ No newline at end of file diff --git a/doc/developer/developer_guide.html b/doc/developer/developer_guide.html deleted file mode 100644 index 77d622221..000000000 --- a/doc/developer/developer_guide.html +++ /dev/null @@ -1,470 +0,0 @@ -<h2 id="Who_is_a_Hubzilla_developer_Should_I_read_this_">Who is a Hubzilla developer? Should I read this?</h2> - -<p>Anyone who contributes to making Hubzilla better is a developer. There are many different and important ways you can contribute to this amazing technology, <em>even if you do not know how to write code</em>. The software itself is only a part of the Hubzilla project. You can contribute by</p> - -<ul><li>translating text to your language so that people around the world have the opportunity to use Hubzilla</li> -<li>promoting Hubzilla and spreading awareness of the platform through blog posts, articles, and word-of-mouth</li> -<li>creating artwork and graphics for project assets such as icons and marketing material</li> -<li>supporting project infrastructure like the project website and demo servers</li> -</ul><p><em>Software</em> developers are of course welcomed; there are so many great ideas to implement and not enough people to make them all a reality! The Hubzilla code base is an advanced and mature system, but the platform is still very flexible and responsive to new ideas.</p> - -<p>This document will help you get started learning and contributing to Hubzilla.</p> - -<h2 id="Versioning_system">Versioning system</h2> - -<p>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.</p> - -<h2 id="Git_repository_branches">Git repository branches</h2> - -<p>There are two official branches of the Hubzilla git repo.</p> - -<ul><li>The stable version is maintained on the <strong>master</strong> branch. The latest commit in this branch is considered to be suitable for production hubs. </li> -<li>Experimental development occurs on the <strong>dev</strong> branch, which is merged into <strong>master</strong> when it is deemed tested and stable enough.</li> -</ul><h2 id="Developer_tools_and_workflows">Developer tools and workflows</h2> - -<h3 id="Hub_Snapshots">Hub Snapshots</h3> - -<p>The <a href="wiki/hubzilla/Hubzilla+Documentation/Hub%2BSnapshots">Hub Snapshots</a> 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.</p> - -<h2 id="Translations">Translations</h2> - -<p>Our translations are managed through Transifex. If you wish to help out translating Hubzilla to another language, sign up on transifex.com, visit <a href="https://www.transifex.com/projects/p/red-matrix/">https://www.transifex.com/projects/p/red-matrix/</a> 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.</p> - -<h3 id="Translation_Process">Translation Process</h3> - -<p>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 -for any language, be it correcting terms or translating Hubzilla to a -currently not supported language, please register an account at transifex.com -and contact the Redmatrix translation team there.</p> - -<p>Translating Hubzilla is simple. Just use the online tool at transifex. If you -don't want to deal with git & co. that is fine, we check the status of the -translations regularly and import them into the source tree at github so that -others can use them.</p> - -<p>We do not include every translation from transifex in the source tree to avoid -a scattered and disturbed overall experience. As an uneducated guess we have a -lower limit of 50% translated strings before we include the language. This -limit is judging only by the amount of translated strings under the assumption -that the most prominent strings for the UI will be translated first by a -translation team. If you feel your translation useable before this limit, -please contact us and we will probably include your teams work in the source -tree.</p> - -<p>If you want to get your work into the source tree yourself, feel free to do so -and contact us with and question that arises. The process is simple and -Hubzilla ships with all the tools necessary.</p> - -<p>The location of the translated files in the source tree is - /view/LNG-CODE/ -where LNG-CODE is the language code used, e.g. de for German or fr for French. -For the email templates (the *.tpl files) just place them into the directory -and you are done. The translated strings come as a "hmessages.po" file from -transifex which needs to be translated into the PHP file Hubzilla uses. To do -so, place the file in the directory mentioned above and use the "po2php" -utility from the util directory of your Hubzilla installation.</p> - -<p>Assuming you want to convert the German localization which is placed in -view/de/hmessages.po you would do the following.</p> - -<ol><li><p>Navigate at the command prompt to the base directory of your -Hubzilla installation</p></li> -<li><p>Execute the po2php script, which will place the translation -in the hstrings.php file that is used by Hubzilla.</p> - -<p>$> php util/po2php.php view/de/hmessages.po</p> - -<p>The output of the script will be placed at view/de/hstrings.php where -froemdoca os expecting it, so you can test your translation mmediately.</p></li> -<li><p>Visit your Hubzilla page to check if it still works in the language you -just translated. If not try to find the error, most likely PHP will give -you a hint in the log/warnings.about the error.</p> - -<p>For debugging you can also try to "run" the file with PHP. This should -not give any output if the file is ok but might give a hint for -searching the bug in the file.</p> - -<p>$> php view/de/hstrings.php</p></li> -<li><p>commit the two files with a meaningful commit message to your git -repository, push it to your fork of the Hubzilla repository at github and -issue a pull request for that commit.</p></li> -</ol><h3 id="Utilities">Utilities</h3> - -<p>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 -translate Hubzilla into another language you wont need any of these tools most -likely but it gives you an idea how the translation process of Hubzilla -works.</p> - -<p>For further information see the utils/README file.</p> - -<h3 id="Known_Problems">Known Problems</h3> - -<ul><li>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 -quirks.</li> -<li>the early translations are based on the friendica translations, if you -some rough translations please let us know or fix them at Transifex.</li> -</ul><h2 id="To_be_organized_information">To-be-organized information</h2> - -<p><strong>Here is how you can join us.</strong></p> - -<p>First, get yourself a working git package on the system where you will be -doing development.</p> - -<p>Create your own github account.</p> - -<p>You may fork/clone the Red repository from <a href="https://github.com/redmatrix/hubzilla.git">https://github.com/redmatrix/hubzilla.git</a>.</p> - -<p>Follow the instructions provided here: <a href="http://help.github.com/fork-a-repo/">http://help.github.com/fork-a-repo/</a> -to create and use your own tracking fork on github</p> - -<p>Then go to your github page and create a "Pull request" when you are ready -to notify us to merge your work.</p> - -<p><strong>Important</strong></p> - -<p>Please pull in any changes from the project repository and merge them with your work <strong>before</strong> issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.</p> - -<p>Also - <strong>test your changes</strong>. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.</p> - -<p><strong>Licensing</strong></p> - -<p>All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything.</p> - -<p><strong>Coding Style</strong></p> - -<p>In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future.</p> - -<ul><li><p>All comments should be in English.</p></li> -<li><p>We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged.</p></li> -<li><p>Indentation is accomplished primarily with tabs using a tab-width of 4.</p></li> -<li><p>String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';"</p></li> -<li><p>Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes.</p></li> -<li><p>Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability.</p></li> -<li><p>Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves.</p></li> -</ul><p><strong>File system layout:</strong></p> - -<p>[addon] optional addons/plugins</p> - -<p>[boot.php] Every process uses this to bootstrap the application structure</p> - -<p>[doc] Help Files</p> - -<p>[images] core required images</p> - -<p>[include] The "model" in MVC - (back-end functions), also contains PHP "executables" for background processing</p> - -<p>[index.php] The front-end controller for web access</p> - -<p>[install] Installation and upgrade files and DB schema</p> - -<p>[library] Third party modules (must be license compatible)</p> - -<p>[mod] Controller modules based on URL pathname (e.g. #^[url=http://sitename/foo]http://sitename/foo[/url] loads mod/foo.php)</p> - -<p>[mod/site/] site-specific mod overrides, excluded from git</p> - -<p>[util] translation tools, main English string database and other miscellaneous utilities</p> - -<p>[version.inc] contains current version (auto-updated via cron for the master repository and distributed via git)</p> - -<p>[view] theming and language files</p> - -<p>[view/(css,js,img,php,tpl)] default theme files</p> - -<p>[view/(en,it,es ...)] language strings and resources</p> - -<p>[view/theme/] individual named themes containing (css,js,img,php,tpl) over-rides</p> - -<p><strong>The Database:</strong></p> - -<table><thead><tr><th>Table</th> - <th>Description</th> -</tr></thead><tbody><tr><td>abconfig</td> - <td>contact table, replaces Friendica 'contact'</td> -</tr><tr><td>abook</td> - <td></td> -</tr><tr><td>account</td> - <td>service provider account</td> -</tr><tr><td>addon</td> - <td></td> -</tr><tr><td>addressbookchanges</td> - <td></td> -</tr><tr><td>addressbooks</td> - <td></td> -</tr><tr><td>app</td> - <td></td> -</tr><tr><td>atoken</td> - <td></td> -</tr><tr><td>attach</td> - <td></td> -</tr><tr><td>auth_codes</td> - <td></td> -</tr><tr><td>cache</td> - <td></td> -</tr><tr><td>cal</td> - <td></td> -</tr><tr><td>calendarchanges</td> - <td></td> -</tr><tr><td>calendarinstances</td> - <td></td> -</tr><tr><td>calendarobjects</td> - <td></td> -</tr><tr><td>calendars</td> - <td></td> -</tr><tr><td>calendarsubscriptions</td> - <td></td> -</tr><tr><td>cards</td> - <td></td> -</tr><tr><td>channel</td> - <td></td> -</tr><tr><td>chat</td> - <td></td> -</tr><tr><td>chatpresence</td> - <td></td> -</tr><tr><td>chatroom</td> - <td></td> -</tr><tr><td>clients</td> - <td></td> -</tr><tr><td>config</td> - <td></td> -</tr><tr><td>conv</td> - <td></td> -</tr><tr><td>dreport</td> - <td></td> -</tr><tr><td>event</td> - <td></td> -</tr><tr><td>group_member</td> - <td></td> -</tr><tr><td>groupmembers</td> - <td></td> -</tr><tr><td>groups</td> - <td></td> -</tr><tr><td>hook</td> - <td></td> -</tr><tr><td>hubloc</td> - <td></td> -</tr><tr><td>iconfig</td> - <td></td> -</tr><tr><td>issue</td> - <td></td> -</tr><tr><td>item</td> - <td></td> -</tr><tr><td>item_id</td> - <td></td> -</tr><tr><td>likes</td> - <td></td> -</tr><tr><td>locks</td> - <td></td> -</tr><tr><td>mail</td> - <td></td> -</tr><tr><td>menu</td> - <td></td> -</tr><tr><td>menu_item</td> - <td></td> -</tr><tr><td>notify</td> - <td></td> -</tr><tr><td>obj</td> - <td></td> -</tr><tr><td>outq</td> - <td></td> -</tr><tr><td>pconfig</td> - <td>personal (per channel) configuration storage</td> -</tr><tr><td>photo</td> - <td></td> -</tr><tr><td>poll</td> - <td></td> -</tr><tr><td>poll_elm</td> - <td></td> -</tr><tr><td>principals</td> - <td></td> -</tr><tr><td>profdef</td> - <td></td> -</tr><tr><td>profext</td> - <td></td> -</tr><tr><td>profile</td> - <td></td> -</tr><tr><td>profile_check</td> - <td></td> -</tr><tr><td>propertystorage</td> - <td></td> -</tr><tr><td>register</td> - <td></td> -</tr><tr><td>schedulingobjects</td> - <td></td> -</tr><tr><td>session</td> - <td></td> -</tr><tr><td>shares</td> - <td></td> -</tr><tr><td>sign</td> - <td></td> -</tr><tr><td>site</td> - <td></td> -</tr><tr><td>source</td> - <td></td> -</tr><tr><td>sys_perms</td> - <td></td> -</tr><tr><td>term</td> - <td></td> -</tr><tr><td>tokens</td> - <td></td> -</tr><tr><td>updates</td> - <td></td> -</tr><tr><td>users</td> - <td></td> -</tr><tr><td>verify</td> - <td></td> -</tr><tr><td>vote</td> - <td></td> -</tr><tr><td>xchan</td> - <td></td> -</tr><tr><td>xchat</td> - <td></td> -</tr><tr><td>xconfig</td> - <td></td> -</tr><tr><td>xign</td> - <td></td> -</tr><tr><td>xlink</td> - <td></td> -</tr><tr><td>xperm</td> - <td></td> -</tr><tr><td>xprof</td> - <td></td> -</tr><tr><td>xtag</td> - <td></td> -</tr></tbody></table><pre><code>* abook - contact table, replaces Friendica 'contact' -* account - service provider account -* addon - registered plugins -* app - peronal app data -* attach - file attachments -* auth_codes - OAuth usage -* cache - OEmbed cache -* channel - replaces Friendica 'user' -* chat - chat room content -* chatpresence - channel presence information for chat -* chatroom - data for the actual chat room -* clients - OAuth usage -* config - main configuration storage -* conv - Diaspora private messages -* event - Events -* fcontact - friend suggestion stuff -* ffinder - friend suggestion stuff -* fserver - obsolete -* fsuggest - friend suggestion stuff -* groups - privacy groups -* group_member - privacy groups -* hook - plugin hook registry -* hubloc - Red location storage, ties a location to an xchan -* item - posts -* item_id - other identifiers on other services for posts -* likes - likes of 'things' -* mail - private messages -* menu - channel menu data -* menu_item - items uses by channel menus -* notify - notifications -* notify-threads - need to factor this out and use item thread info on notifications -* obj - object data for things (x has y) -* outq - output queue -* pconfig - personal (per channel) configuration storage -* photo - photo storage -* poll - data for polls -* poll_elm - data for poll elements -* profdef - custom profile field definitions -* profext - custom profile field data -* profile - channel profiles -* profile_check - DFRN remote auth use, may be obsolete -* register - registrations requiring admin approval -* session - web session storage -* shares - shared item information -* sign - Diaspora signatures. To be phased out. -* site - site table to find directory peers -* source - channel sources data -* spam - unfinished -* sys_perms - extensible permissions for the sys channel -* term - item taxonomy (categories, tags, etc.) table -* tokens - OAuth usage -* updates - directory sync updates -* verify - general purpose verification structure -* vote - vote data for polls -* xchan - replaces 'gcontact', list of known channels in the universe -* xchat - bookmarked chat rooms -* xconfig - as pconfig but for channels with no local account -* xlink - "friends of friends" linkages derived from poco -* xprof - if this hub is a directory server, contains basic public profile info of everybody in the network -* xtag - if this hub is a directory server, contains tags or interests of everybody in the network -</code></pre> - -<p><strong>How to theme Hubzilla</strong></p> - -<p>This is a short documentation on what I found while trying to modify Hubzilla's appearance.</p> - -<p>First, you'll need to create a new theme. This is in /view/theme, and I chose to copy 'redbasic' since it's the only available for now. Let's assume I named it .</p> - -<p>Oh, and don't forget to rename the _init function in /php/theme.php to be _init() instead of redbasic_init().</p> - -<p>At that point, if you need to add javascript or css files, add them to /js or /css, and then "register" them in _init() through head_add_js('file.js') and head_add_css('file.css').</p> - -<p>Now you'll probably want to alter a template. These can be found in in /view/tpl OR view//tpl. All you should have to do is copy whatever you want to tweak from the first place to your theme's own tpl directory.</p> - -<p>We're pretty relaxed when it comes to developers. We don't have a lot of rules. Some of us are over-worked and if you want to help we're happy to let you help. That said, attention to a few guidelines will make the process smoother and make it easier to work together. We have developers from across the globe with different abilities and different cultural backgrounds and different levels of patience. Our primary rule is to respect others. Sometimes this is hard and sometimes we have very different opinions of how things should work, but if everybody makes an effort, we'll get along just fine.</p> - -<p><strong>Here is how you can join us.</strong></p> - -<p>First, get yourself a working git package on the system where you will be -doing development.</p> - -<p>Create your own github account.</p> - -<p>You may fork/clone the Red repository from [url=https://github.com/redmatrix/hubzilla.git]https://github.com/redmatrix/hubzilla.git[/url]</p> - -<p>Follow the instructions provided here: [url=http://help.github.com/fork-a-repo/]http://help.github.com/fork-a-repo/[/url] -to create and use your own tracking fork on github</p> - -<p>Then go to your github page and create a "Pull request" when you are ready -to notify us to merge your work.</p> - -<p><strong>Translations</strong></p> - -<p>Our translations are managed through Transifex. If you wish to help out translating the $Projectname to another language, sign up on transifex.com, visit [url=https://www.transifex.com/projects/p/red-matrix/]https://www.transifex.com/projects/p/red-matrix/[/url] 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.</p> - -<p><strong>Important</strong></p> - -<p>Please pull in any changes from the project repository and merge them with your work <strong>before</strong> issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.</p> - -<p>Also - <strong>test your changes</strong>. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.</p> - -<p>Further documentation can be found at the Github wiki pages at: [url=https://github.com/friendica/red/wiki]https://github.com/friendica/red/wiki[/url]</p> - -<p><strong>Licensing</strong></p> - -<p>All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything.</p> - -<p><strong>Concensus Building</strong></p> - -<p>Code changes which fix an obvious bug are pretty straight-forward. For instance if you click "Save" and the thing you're trying to save isn't saved, it's fairly obvious what the intended behaviour should be. Often when developing feature requests, it may affect large numbers of community members and it's possible that other members of the community won't agree with the need for the feature, or with your proposed implementation. They may not see something as a bug or a desirable feature.</p> - -<p>We encourage consensus building within the community when it comes to any feature which might be considered controversial or where there isn't unanimous decision that the proposed feature is the correct way to accomplish the task. The first place to pitch your ideas is to [url=https://zothub.com/channel/one]Channel One[/url]. Others may have some input or be able to point out facets of your concept which might be problematic in our environment. But also, you may encounter opposition to your plan. This doesn't mean you should stop and/or ignore the feature. Listen to the concerns of others and try and work through any implementation issues.</p> - -<p>There are places where opposition cannot be resolved. In these cases, please consider making your feature <strong>optional</strong> or non-default behaviour that must be specifically enabled. This technique can often be used when a feature has significant but less than unanimous support. Those who desire the feature can turn it on and those who don't want it - will leave it turned off.</p> - -<p>If a feature uses other networks or websites and or is only seen as desirable by a small minority of the community, consider making the functionality available via an addon or plugin. Once again, those who don't desire the feature won't need to install it. Plugins are relatively easy to create and "hooks" can be easily added or modified if the current hooks do not do what is needed to allow your plugin to work.</p> - -<p><strong>Coding Style</strong></p> - -<p>In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future.</p> - -<ul><li><p>All comments should be in English.</p></li> -<li><p>We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged.</p></li> -<li><p>Indentation is accomplished primarily with tabs using a tab-width of 4.</p></li> -<li><p>String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';"</p></li> -<li><p>Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes.</p></li> -<li><p>Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability.</p></li> -<li><p>Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves.</p></li> -<li><p>Some functions take arguments in argc/argv style like main() in C or function args in bash or Perl. Urls are broken up within a module. e.g, given "http://example.com/module/arg1/arg2", then $this->argc will be 3 (integer) and $this->argv will contain: [0] => 'module', [1] => 'arg1', [2] => 'arg2'. There will always be one argument. If provided a naked domain URL, $this->argv[0] is set to "home".</p></li> -</ul> -
\ No newline at end of file diff --git a/doc/developer/developer_guide.md b/doc/developer/developer_guide.md new file mode 100644 index 000000000..3c0f7294d --- /dev/null +++ b/doc/developer/developer_guide.md @@ -0,0 +1,422 @@ +## 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 + +* translating text to your language so that people around the world have the opportunity to use Hubzilla +* promoting Hubzilla and spreading awareness of the platform through blog posts, articles, and word-of-mouth +* creating artwork and graphics for project assets such as icons and marketing material +* supporting project infrastructure like the project website and demo servers + +_Software_ developers are of course welcomed; there are so many great ideas to implement and not enough people to make them all a reality! The Hubzilla code base is an advanced and mature system, but the platform is still very flexible and responsive to new ideas. + +This document will help you get started learning and contributing to Hubzilla. + +## 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 + +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 + +### Hub Snapshots + +The [[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 + +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 + +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 +for any language, be it correcting terms or translating Hubzilla to a +currently not supported language, please register an account at transifex.com +and contact the Redmatrix translation team there. + +Translating Hubzilla is simple. Just use the online tool at transifex. If you +don't want to deal with git & co. that is fine, we check the status of the +translations regularly and import them into the source tree at github so that +others can use them. + +We do not include every translation from transifex in the source tree to avoid +a scattered and disturbed overall experience. As an uneducated guess we have a +lower limit of 50% translated strings before we include the language. This +limit is judging only by the amount of translated strings under the assumption +that the most prominent strings for the UI will be translated first by a +translation team. If you feel your translation useable before this limit, +please contact us and we will probably include your teams work in the source +tree. + +If you want to get your work into the source tree yourself, feel free to do so +and contact us with and question that arises. The process is simple and +Hubzilla ships with all the tools necessary. + +The location of the translated files in the source tree is + /view/LNG-CODE/ +where LNG-CODE is the language code used, e.g. de for German or fr for French. +For the email templates (the *.tpl files) just place them into the directory +and you are done. The translated strings come as a "hmessages.po" file from +transifex which needs to be translated into the PHP file Hubzilla uses. To do +so, place the file in the directory mentioned above and use the "po2php" +utility from the util directory of your Hubzilla installation. + +Assuming you want to convert the German localization which is placed in +view/de/hmessages.po you would do the following. + +1. Navigate at the command prompt to the base directory of your + Hubzilla installation + +2. Execute the po2php script, which will place the translation + in the hstrings.php file that is used by Hubzilla. + + $> php util/po2php.php view/de/hmessages.po + + The output of the script will be placed at view/de/hstrings.php where + froemdoca os expecting it, so you can test your translation mmediately. + +3. Visit your Hubzilla page to check if it still works in the language you + just translated. If not try to find the error, most likely PHP will give + you a hint in the log/warnings.about the error. + + For debugging you can also try to "run" the file with PHP. This should + not give any output if the file is ok but might give a hint for + searching the bug in the file. + + $> php view/de/hstrings.php + +4. commit the two files with a meaningful commit message to your git + repository, push it to your fork of the Hubzilla repository at github and + issue a pull request for that commit. + +### 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 +translate Hubzilla into another language you wont need any of these tools most +likely but it gives you an idea how the translation process of Hubzilla +works. + +For further information see the utils/README file. + +### 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 + quirks. +* 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 + +**Here is how you can join us.** + +First, get yourself a working git package on the system where you will be +doing development. + +Create your own github account. + +You may fork/clone the Red repository from [https://github.com/redmatrix/hubzilla.git](https://github.com/redmatrix/hubzilla.git). + +Follow the instructions provided here: [http://help.github.com/fork-a-repo/](http://help.github.com/fork-a-repo/) +to create and use your own tracking fork on github + +Then go to your github page and create a "Pull request" when you are ready +to notify us to merge your work. + + +**Important** + +Please pull in any changes from the project repository and merge them with your work **before** issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions. + +Also - **test your changes**. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code. + + +**Licensing** + +All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything. + +**Coding Style** + +In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future. + +* All comments should be in English. + +* We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged. + +* Indentation is accomplished primarily with tabs using a tab-width of 4. + +* String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';" + +* Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes. + +* Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability. + +* Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves. + + +**File system layout:** + +[addon] optional addons/plugins + +[boot.php] Every process uses this to bootstrap the application structure + +[doc] Help Files + +[images] core required images + +[include] The "model" in MVC - (back-end functions), also contains PHP "executables" for background processing + +[index.php] The front-end controller for web access + +[install] Installation and upgrade files and DB schema + +[library] Third party modules (must be license compatible) + +[mod] Controller modules based on URL pathname (e.g. #^[url=http://sitename/foo]http://sitename/foo[/url] loads mod/foo.php) + +[mod/site/] site-specific mod overrides, excluded from git + +[util] translation tools, main English string database and other miscellaneous utilities + +[version.inc] contains current version (auto-updated via cron for the master repository and distributed via git) + +[view] theming and language files + +[view/(css,js,img,php,tpl)] default theme files + +[view/(en,it,es ...)] language strings and resources + +[view/theme/] individual named themes containing (css,js,img,php,tpl) over-rides + +**The Database:** + + +| Table | Description | +|-------------------------|--------------------------------------------------------| +| abconfig | contact table, replaces Friendica 'contact' | +| abook | | +| account | service provider account | +| addon | | +| addressbookchanges | | +| addressbooks | | +| app | | +| atoken | | +| attach | | +| auth_codes | | +| cache | | +| cal | | +| calendarchanges | | +| calendarinstances | | +| calendarobjects | | +| calendars | | +| calendarsubscriptions | | +| cards | | +| channel | | +| chat | | +| chatpresence | | +| chatroom | | +| clients | | +| config | | +| conv | | +| dreport | | +| event | | +| group_member | | +| groupmembers | | +| groups | | +| hook | | +| hubloc | | +| iconfig | | +| issue | | +| item | | +| item_id | | +| likes | | +| locks | | +| mail | | +| menu | | +| menu_item | | +| notify | | +| obj | | +| outq | | +| pconfig | personal (per channel) configuration storage | +| photo | | +| poll | | +| poll_elm | | +| principals | | +| profdef | | +| profext | | +| profile | | +| profile_check | | +| propertystorage | | +| register | | +| schedulingobjects | | +| session | | +| shares | | +| sign | | +| site | | +| source | | +| sys_perms | | +| term | | +| tokens | | +| updates | | +| users | | +| verify | | +| vote | | +| xchan | | +| xchat | | +| xconfig | | +| xign | | +| xlink | | +| xperm | | +| xprof | | +| xtag | | + + + * abook - contact table, replaces Friendica 'contact' + * account - service provider account + * addon - registered plugins + * app - peronal app data + * attach - file attachments + * auth_codes - OAuth usage + * cache - OEmbed cache + * channel - replaces Friendica 'user' + * chat - chat room content + * chatpresence - channel presence information for chat + * chatroom - data for the actual chat room + * clients - OAuth usage + * config - main configuration storage + * conv - Diaspora private messages + * event - Events + * fcontact - friend suggestion stuff + * ffinder - friend suggestion stuff + * fserver - obsolete + * fsuggest - friend suggestion stuff + * groups - privacy groups + * group_member - privacy groups + * hook - plugin hook registry + * hubloc - Red location storage, ties a location to an xchan + * item - posts + * item_id - other identifiers on other services for posts + * likes - likes of 'things' + * mail - private messages + * menu - channel menu data + * menu_item - items uses by channel menus + * notify - notifications + * notify-threads - need to factor this out and use item thread info on notifications + * obj - object data for things (x has y) + * outq - output queue + * pconfig - personal (per channel) configuration storage + * photo - photo storage + * poll - data for polls + * poll_elm - data for poll elements + * profdef - custom profile field definitions + * profext - custom profile field data + * profile - channel profiles + * profile_check - DFRN remote auth use, may be obsolete + * register - registrations requiring admin approval + * session - web session storage + * shares - shared item information + * sign - Diaspora signatures. To be phased out. + * site - site table to find directory peers + * source - channel sources data + * spam - unfinished + * sys_perms - extensible permissions for the sys channel + * term - item taxonomy (categories, tags, etc.) table + * tokens - OAuth usage + * updates - directory sync updates + * verify - general purpose verification structure + * vote - vote data for polls + * xchan - replaces 'gcontact', list of known channels in the universe + * xchat - bookmarked chat rooms + * xconfig - as pconfig but for channels with no local account + * xlink - "friends of friends" linkages derived from poco + * xprof - if this hub is a directory server, contains basic public profile info of everybody in the network + * xtag - if this hub is a directory server, contains tags or interests of everybody in the network + + +**How to theme Hubzilla** + +This is a short documentation on what I found while trying to modify Hubzilla's appearance. + +First, you'll need to create a new theme. This is in /view/theme, and I chose to copy 'redbasic' since it's the only available for now. Let's assume I named it . + +Oh, and don't forget to rename the _init function in /php/theme.php to be _init() instead of redbasic_init(). + +At that point, if you need to add javascript or css files, add them to /js or /css, and then "register" them in _init() through head_add_js('file.js') and head_add_css('file.css'). + +Now you'll probably want to alter a template. These can be found in in /view/tpl OR view//tpl. All you should have to do is copy whatever you want to tweak from the first place to your theme's own tpl directory. + + +We're pretty relaxed when it comes to developers. We don't have a lot of rules. Some of us are over-worked and if you want to help we're happy to let you help. That said, attention to a few guidelines will make the process smoother and make it easier to work together. We have developers from across the globe with different abilities and different cultural backgrounds and different levels of patience. Our primary rule is to respect others. Sometimes this is hard and sometimes we have very different opinions of how things should work, but if everybody makes an effort, we'll get along just fine. + +**Here is how you can join us.** + +First, get yourself a working git package on the system where you will be +doing development. + +Create your own github account. + +You may fork/clone the Red repository from [url=https://github.com/redmatrix/hubzilla.git]https://github.com/redmatrix/hubzilla.git[/url] + +Follow the instructions provided here: [url=http://help.github.com/fork-a-repo/]http://help.github.com/fork-a-repo/[/url] +to create and use your own tracking fork on github + +Then go to your github page and create a "Pull request" when you are ready +to notify us to merge your work. + +**Translations** + +Our translations are managed through Transifex. If you wish to help out translating the $Projectname to another language, sign up on transifex.com, visit [url=https://www.transifex.com/projects/p/red-matrix/]https://www.transifex.com/projects/p/red-matrix/[/url] 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. + + +**Important** + +Please pull in any changes from the project repository and merge them with your work **before** issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions. + +Also - **test your changes**. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code. + +Further documentation can be found at the Github wiki pages at: [url=https://github.com/friendica/red/wiki]https://github.com/friendica/red/wiki[/url] + +**Licensing** + +All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything. + +**Concensus Building** + +Code changes which fix an obvious bug are pretty straight-forward. For instance if you click "Save" and the thing you're trying to save isn't saved, it's fairly obvious what the intended behaviour should be. Often when developing feature requests, it may affect large numbers of community members and it's possible that other members of the community won't agree with the need for the feature, or with your proposed implementation. They may not see something as a bug or a desirable feature. + +We encourage consensus building within the community when it comes to any feature which might be considered controversial or where there isn't unanimous decision that the proposed feature is the correct way to accomplish the task. The first place to pitch your ideas is to [url=https://zothub.com/channel/one]Channel One[/url]. Others may have some input or be able to point out facets of your concept which might be problematic in our environment. But also, you may encounter opposition to your plan. This doesn't mean you should stop and/or ignore the feature. Listen to the concerns of others and try and work through any implementation issues. + +There are places where opposition cannot be resolved. In these cases, please consider making your feature **optional** or non-default behaviour that must be specifically enabled. This technique can often be used when a feature has significant but less than unanimous support. Those who desire the feature can turn it on and those who don't want it - will leave it turned off. + +If a feature uses other networks or websites and or is only seen as desirable by a small minority of the community, consider making the functionality available via an addon or plugin. Once again, those who don't desire the feature won't need to install it. Plugins are relatively easy to create and "hooks" can be easily added or modified if the current hooks do not do what is needed to allow your plugin to work. + + +**Coding Style** + +In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future. + +* All comments should be in English. + +* We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged. + +* Indentation is accomplished primarily with tabs using a tab-width of 4. + +* String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';" + +* Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes. + +* Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability. + +* Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves. + +* Some functions take arguments in argc/argv style like main() in C or function args in bash or Perl. Urls are broken up within a module. e.g, given "http://example.com/module/arg1/arg2", then $this->argc will be 3 (integer) and $this->argv will contain: [0] => 'module', [1] => 'arg1', [2] => 'arg2'. There will always be one argument. If provided a naked domain URL, $this->argv[0] is set to "home".
\ No newline at end of file diff --git a/doc/member/member_faq.bb b/doc/member/member_faq.bb new file mode 100644 index 000000000..bb70dc4d9 --- /dev/null +++ b/doc/member/member_faq.bb @@ -0,0 +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] +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] +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] +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] +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_faq.html b/doc/member/member_faq.html deleted file mode 100644 index fa124c1b1..000000000 --- a/doc/member/member_faq.html +++ /dev/null @@ -1,19 +0,0 @@ -<p><strong>Frequently Asked Questions</strong></p> - -<ul id="member-faq-toc"> - <li><a href="/help/member/member_faq#I_am_able_to_edit_a_post_s_text_after_I_saved_it_but_is_there_a_way_to_change_the_permissions_">I am able to edit a post's text after I saved it, but is there a way to change the permissions?</a></li> - <li><a href="/help/member/member_faq#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_">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???</a></li> - <li><a href="/help/member/member_faq#I_can_t_see_private_resources">I can't see private resources</a></li> - <li><a href="/help/member/member_faq#There_are_a_lot_of_foreign_language_posts_Let_s_auto_translate_them_">There are a lot of foreign language posts. Let's auto-translate them.</a></li> -</ul> - -<hr> - -<h1 id="I_am_able_to_edit_a_post_s_text_after_I_saved_it_but_is_there_a_way_to_change_the_permissions_">I am able to edit a post's text after I saved it, but is there a way to change the permissions?</h1> -<br>Short answer: No, there isn't. There are reasons. You are able to change permissions 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 Hubzilla 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 Hubzilla 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. <br>If a posting is public this is even harder, as Hubzilla 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.<br><br> -<h1 id="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_">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???</h1> -<br>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. :)<br> -<h1 id="I_can_t_see_private_resources">I can't see private resources</h1> -<br>You have probably disabled third party cookies. You need to enable them for remote authentication to work.<br> -<h1 id="There_are_a_lot_of_foreign_language_posts_Let_s_auto_translate_them_">There are a lot of foreign language posts. Let's auto-translate them.</h1> -<br>There are also a lot of <strong>private</strong> 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 <strong><em>Apertium</em></strong> 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 new file mode 100644 index 000000000..9824de390 --- /dev/null +++ b/doc/member/member_guide.bb @@ -0,0 +1,362 @@ +[h1]Overview[/h1] + +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] + +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. + +[b]Your Email Address[/b] + +Please provide a valid email address. Your email address is never published. This address will be used to activate your account, to (optionally) send email notifications for incoming messages or items, [i]and to recover lost passwords[/i]. + +[b]Password[/b] + +Enter a password of your choice, and repeat it in the second box to ensure it was typed correctly. As $Projectname offers a decentralised identity, your account can log you in to many other websites. + +[b]Terms Of Service[/b] + +Click the link to read the site's [zrl=[baseurl]/help/TermsOfService]Terms of Service[/zrl]. Once you've read them, tick the box in the register form to confirm. + +[b]Register[/b] + +Once you have provided the necessary details, click the 'Register' button. Some sites may require administrator approval before the registration is processed, and you will be alerted if this is the case. Please watch your email (including spam folders) for your registration approval. + +[b]Create a Channel[/b] + +Next, you will be presented with the "Add a channel" screen. Normally, your first channel will be one that represents you - so using your own name (or psuedonym) as the channel name is a good idea. The channel name should be thought of as a title, or brief description of your channel. The "choose a short nickname" box is similar to a "username" field. We will use whatever you enter here to create a channel address, which other people will use to connect to you, and you will use to log in to other sites. This looks like an email address, and takes the form nickname@siteyouregisteredat.xyz + +When your channel is created you will be taken straight to your settings page where you can define permissions, enable features, etc. All these things are covered in the appropriate section of the helpfiles. + +See Also +[zrl=[baseurl]/help/accounts_profiles_channels_basics]The Basics about Identities within $Projectname[/zrl] +[zrl=[baseurl]/help/accounts]Accounts[/zrl] +[zrl=[baseurl]/help/profiles]Profiles[/zrl] +[zrl=[baseurl]/help/permissions]Permissions[/zrl] +[zrl=[baseurl]/help/remove_account]Remove Account[/zrl] + +[b]Profiles[/b] + +$Projectname has unlimited profiles. You may use different profiles to show different "sides of yourself" to different audiences. This is different to having different channels. Different channels allow for completely different sets of information. You may have a channel for yourself, a channel for your sports team, a channel for your website, or whatever else. A profile allows for finely graded "sides" of each channel. For example, your default public profile might say "Hello, I'm Fred, and I like laughing". You may show your close friends a profile that adds "and I also enjoy dwarf tossing". + +You always have a profile known as your "default" or "public" profile. This profile is always available to the general public and cannot be hidden (there may be rare exceptions on privately run or disconnected sites). You may, and probably should restrict the information you make available on your public profile. + +That said, if you want other friends to be able to find you, it helps to have the following information in your public profile... + +[ul][*]Your real name or at least a nickname everybody knows +[*]A photo of you +[*]Your location on the planet, at least to a country level.[/ul] + +In addition, if you'd like to meet people that share some general interests with you, please take a moment and add some "Keywords" to your profile. Such as "music, linux, photography" or whatever. You can add as many keywords as you like. + +To create an alternate profile, first go to [zrl=[baseurl]/settings/features]Settings > Additional Features[/zrl] and enable "Multiple Profiles" there, otherwise you won't have the ability to use more than just your default profile. + +Then select "Edit Profiles" from the menu of your $Projectname site. You may edit an existing profile, change the profile photo, add things to a profile or create a new profile. You may also create a "clone" of an existing profile if you only wish to change a few items but don't wish to enter all the information again. To do that, click on the profile you want to clone and choose "Clone this profile" there. + +In the list of your profiles, you can also choose the contacts who can see a specific profile. Just click on "Edit visibility" next to the profile in question (only available for the profiles that are not your default profile) and then click on user images to add them to or remove them from the group of people who can see this profile. + +Once a profile has been selected, when the person views your profile, they will see the private profile you have assigned. If they are not authenticated, they will see your public profile. + +There is a setting which allows you to publish your profile to a directory and ensure that it can be found by others. You can change this setting on the "Settings" page. + +If you do not wish to be found be people unless you give them your channel address, you may leave your profile unpublished. + +[b]Keywords and Directory Search[/b] + +On the directory page, you may search for people with published profiles. Currently, only the name field and the keywords are searched. You may also include such keywords in your default profile - which may be used to search for common interests with other members. Keywords are used in the channel suggestion tool and although they aren't visible in the directory, they are shown if people visit your profile page. + +On your Connnections page and in the directory there is a link to "Suggestions" or "Channel Suggestions", respectively. This will find channels who have matching and/or similar keywords. The more keywords you provide, the more relevant the search results that are returned. These are sorted by relevance. + +See Also + +[zrl=[baseurl]/help/AdvancedSearch]Advanced Searching[/zrl] + +[h2]Channels[/h2] + +[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] + +[b]Mostly Public[/b] + +The channel is a typical social networking profile. By default posts and published items are public, but one can over-ride this when creating the item and restrict it. You are listed in the directory. Your online presence and connections are visible to others. + + +[b]Restricted[/b] + +By default all posts and published items are sent to your 'Friends' privacy group and not made public. New friends are added to this privacy group. You can over-ride this and create a public post or published item if you desire. You are listed in the directory. Your online presence (for chat) and your connections (friends) are visible to your profile viewers. + +[b]Private[/b] + +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] + +[b]Mostly Public[/b] + +The channel is a typical forum. By default posts and published items are public. Members may post by @mention+ or wall-to-wall post. Posting photos and other published items is blocked. The channel is visible in the directory. Members are added automatically. + + +[b]Restricted[/b] + +By default all posts and published items are sent to the channel's 'Friends' privacy group. New friends are added to this privacy group. Members may post by @mention+ or wall-to-wall post, but posts and replies may also be seen by other receipients of the top-level post who are not members. The channel is visible in the directory. Members must be manually added by the forum owner. + +[b]Private[/b] + +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] + + +[b]Public[/b] + +Similiar to Social - Mostly Public, but tailored for RSS feed sources. Items may be freely republished and sourced. Online presence is meaningless, therefore hidden. New connections are automatically approved. + + +[b]Restricted[/b] + +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] + +[b]Celebrity/Soapbox[/b] + +Listed in directory. Communications are by default public. Online presence is hidden. No commenting or feedback of any form is allowed, though connections have the ability to "like" your profile. + + +[b]Group Repository[/b] + +A public forum which allows members to post files/photos/webpages. + + +[h2]Custom/Expert Mode[/h2] + +Set all the privacy and permissions manually to suit your specific needs. + + +[h1]Connecting To Channels[/h1] + +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? + +First, you need to find some channels to connect to. There are two primary ways of doing this. Firstly, setting the "Can send me their channel stream and posts" permission to "Anybody in this network" will bring posts from complete strangers to your matrix. This will give you a lot of public content and should hopefully help you find interesting, entertaing people, forums, and channels. + +The next thing you can do is look at the Directory. The directory is available on every $Projectname website which means searching from your own site will bring in results from the entire network. You can search by name, interest, location and keyword. This is incomplete, so we'll improve this paragraph later. + +To connect with other $Projectname channels: + +Visit their profile by clicking their photograph in the directory, matrix, or comments, and it will open their channel home page in the channel viewer. At the left hand side of the screen, you will usually see a link called "connect". Click it, and you're done. Depending on the settings of the channel you are connecting to, you may need to wait for them to approve your connection, but no further action is needed on your part. Once you've initiated the connection, you will be taken to the connection editor. This allows you to assign specific permissions for this channel. If you don't allow any permissions, communication will be very limited. There are some quick links which you can use to avoid setting individual permissions. To provide a social network environment, "Full Sharing" is recommended. You may review the settings that are applied with the quick links to ensure they are suitable for the channel you are connecting with and adjust if necessary. Then scroll to the bottom of the page and click "Submit". + +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] + +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. + +Here's their meaning: + +[b]Blocked:[/b] the channel can't read your items regardless of permissions, nor can it write to your channel. + +[b]Ignored:[/b] the channel can read your items if it has permission, but can't write to your channel. + +[b]Hidden:[/b] the channel does not show up in your profile's connections list, noone can see you're connected, but beware they may still show up to your other connections, for example in post replies. + +[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] + +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] +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] + +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] + +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] + +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. + +We highly recommend that you use the "typical social network" settings when you create your first channel, as it allows others to communicate with you and help you out if you have difficulty. You will find that these settings allow you as much privacy as you desire - when you desire it; but also allow you to communicate in public if you choose to. You are free to use much more private settings once you have learned your way around. + + +[dl terms="l"] +[*= The scopes of permissions are:] +[dl terms="i"] + [*= Nobody Except Yourself ] This is self explanatory. Only you will be allowed access. + + [*= Only those you specifically allow ] By default, people you are not connected to, and all new contacts will have this permission denied. You will be able to make exceptions for individual channels on their contact edit screen. + + [*= Anybody in your address book ] Anybody you do not know will have this permission denied, but anybody you accept as a contact will have this permission approved. This is the way most legacy platforms handle permissions. + + [*= Anybody On This Hub ] Anybody with a channel on the same hub/website as you will have permission approved. Anybody who is registered at a different hub will have this permission denied. + + [*= Anybody in this network ] Anybody in $Projectname will have this permission approved. Even complete strangers. However, anybody not logged in/authenticated will have this permission denied. + + [*= Anybody authenticated ] This is similar to "anybody in this network" except that it can include anybody who can authenticate by any means - and therefore [i]may[/i] include visitors from other networks. + + [*=Guest Access Token] This allows you to share a file, folder, photo, album, or channel with a specific person or group of people. They don't need to be Hubzilla members. You can set an expiration for the Access Token. + + [*= Anybody on the internet ] Completely public. This permission will be approved for anybody at all. +[/dl] +[*= The individual permissions are:] +[dl terms="i"] + [*= Can view my "public" stream and posts. ] This permision determines who can view your channel "stream" that is, the non-private posts that appear on the "home" tab when you're logged in. + + [*= Can view my "public" channel profile. ] This permission determines who can view your channel's profile. This refers to the "about" tab + + [*= Can view my "public" photo albums. ] This permission determines who can view your photo albums. Individual photographs may still be posted to a more private audience. + + [*= Can view my "public" address book. ] This permission determines who can view your contacts. These are the connections displayed in the "View connections" section. + + [*= Can view my "public" file storage. ] This permission determines who can view your public files stored in your cloud. + + [*= Can view my "public" pages. ] This permission determines who can view your public web pages. + + [*= Can send me their channel stream and posts. ] This permission determines whose posts you will view. If your channel is a personal channel (ie, you as a person), you would probably want to set this to "anyone in my address book" at a minimum. A personal notes channel would probably want to choose "nobody except myself". Setting this to "Anybody in the network" will show you posts from complete strangers, which is a good form of discovery. + + [*= Can post on my channel page ("wall"). ] This permission determines who can write to your wall when clicking through to your channel. + + [*= Can comment on my posts. ] This permission determines who can comment on posts you create. Normally, you would want this to match your "can view my public stream and posts" permission + + [*= Can send me private mail messages. ] This determines who can send you private messages (zotmail). + + [*= Can post photos to my photo albums. ] This determines who can post photographs in your albums. This is very useful for forum-like channels where connections may not be connected to each other. + + [*= Can forward to all my channel contacts via post tags. ] Using @- mentions will reproduce a copy of your post on the profile specified, as though you posted on the channel wall. This determines if people can post to your channel in this way. + + [*= Can chat with me (when available). ] This determines who can join the public chat rooms created by your channel. + + [*= Can write to my "public" file storage. ] This determines who can upload files to your public file storage, or 'cloud'. + + [*= Can edit my "public" pages. ] This determines who can edit your webpages. This is useful for wikis or sites with multiple editors. + + [*= Can administer my channel resources. ] This determines who can have full control of your channel. This should normally be set to "nobody except myself". +[/dl][/dl] +[i]Note:[/i] +Plugins/addons may provide special permission settings, so you may be offered additional permission settings beyond what is described here. + +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] + +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] + +$Projectname provides an ability to store privately and/or share arbitrary files with friends. + +You may either upload files from your computer into your storage area, or copy them directly from the operating system using the WebDAV protocol. + +On many public servers there may be limits on disk usage. + +[h2]File Attachments[/h2] + +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] + +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] + +See: [zrl=[baseurl]/help/member/member_guide#Cloud_Desktop_Clients]Cloud Desktop Clients[/zrl] + +[h2]Permissions[/h2] + +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] + +[h3]Windows Clients[/h3] +[list] +[*][zrl=[baseurl]/help/dav_windows]Windows Internal Client[/zrl] +[/list] + +[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] + +[h3]Server Notes[/h3] + +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] + +[h2]Remove Channel[/h2] + +Go to the bottom of your channel settings page or visit the URL: + + [baseurl]/removeme + +You will need to confirm your password and the channel you are currently logged into will be removed. + +This is irreversible. + +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] + +Go to the bottom of your account settings page or visit the URL: + + [baseurl]/removeaccount + +You will need to confirm your password and the account you are currently logged into will be removed. + +This is irreversible. + +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/member/member_guide.html b/doc/member/member_guide.html deleted file mode 100644 index 62a4cdabe..000000000 --- a/doc/member/member_guide.html +++ /dev/null @@ -1,460 +0,0 @@ - -<h1 id="overview">Overview</h1> -<p> While many features and capabilities of -Hubzilla 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 <strong>decentralized</strong> nature of the grid; others are associated -with the advanced <strong>permissions system</strong> 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. </p> - - -<h1 id="Registration">Registration</h1> -Not all Hubzilla 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 Hubzilla sites are linked, it -does not matter where your account resides.<br><br><strong>Your Email -Address</strong><br><br>Please provide a valid email address. Your email address -is never published. This address will be used to activate your account, to -(optionally) send email notifications for incoming messages or items, <em>and to -recover lost passwords</em>.<br><br><strong>Password</strong><br><br>Enter a -password of your choice, and repeat it in the second box to ensure it was typed -correctly. As Hubzilla offers a decentralised identity, your account can log you -in to many other websites.<br><br><strong>Terms Of Service</strong><br><br>Click -the link to read the site's <a class="zrl" -href="[baseurl]/help/TermsOfService">Terms of Service</a>. Once you've read -them, tick the box in the register form to -confirm.<br><br><strong>Register</strong><br><br>Once you have provided the -necessary details, click the 'Register' button. Some sites may require -administrator approval before the registration is processed, and you will be -alerted if this is the case. Please watch your email (including spam folders) -for your registration approval.<br><br><strong>Create a -Channel</strong><br><br>Next, you will be presented with the "Add a channel" -screen. Normally, your first channel will be one that represents you - so using -your own name (or psuedonym) as the channel name is a good idea. The channel -name should be thought of as a title, or brief description of your channel. The -"choose a short nickname" box is similar to a "username" field. We will use -whatever you enter here to create a channel address, which other people will use -to connect to you, and you will use to log in to other sites. This looks like an -email address, and takes the form nickname@siteyouregisteredat.xyz<br><br>When -your channel is created you will be taken straight to your settings page where -you can define permissions, enable features, etc. All these things are covered -in the appropriate section of the helpfiles.<br><br>See Also<br><a class="zrl" -href="[baseurl]/help/accounts_profiles_channels_basics">The Basics about -Identities within Hubzilla</a><br><a class="zrl" -href="[baseurl]/help/accounts">Accounts</a><br><a class="zrl" -href="[baseurl]/help/profiles">Profiles</a><br><a class="zrl" -href="[baseurl]/help/permissions">Permissions</a><br><a class="zrl" -href="[baseurl]/help/remove_account">Remove Account</a> - -<h1 id="Profiles">Profiles</h1> -Hubzilla has unlimited profiles. You may use -different profiles to show different "sides of yourself" to different audiences. -This is different to having different channels. Different channels allow for -completely different sets of information. You may have a channel for yourself, a -channel for your sports team, a channel for your website, or whatever else. A -profile allows for finely graded "sides" of each channel. For example, your -default public profile might say "Hello, I'm Fred, and I like laughing". You may -show your close friends a profile that adds "and I also enjoy dwarf -tossing".<br><br>You always have a profile known as your "default" or "public" -profile. This profile is always available to the general public and cannot be -hidden (there may be rare exceptions on privately run or disconnected sites). -You may, and probably should restrict the information you make available on your -public profile.<br><br>That said, if you want other friends to be able to find -you, it helps to have the following information in your public -profile...<br><br><ul class="listbullet" style="list-style-type: -circle;"><li>Your real name or at least a nickname everybody knows<br></li><li>A -photo of you<br></li><li>Your location on the planet, at least to a country -level.</li></ul><br><br>In addition, if you'd like to meet people that share -some general interests with you, please take a moment and add some "Keywords" to -your profile. Such as "music, linux, photography" or whatever. You can add as -many keywords as you like.<br><br>To create an alternate profile, first go to <a -class="zrl" href="[baseurl]/settings/features">Settings > Additional -Features</a> and enable "Multiple Profiles" there, otherwise you won't have the -ability to use more than just your default profile.<br><br>Then select "Edit -Profiles" from the menu of your Hubzilla site. You may edit an existing profile, -change the profile photo, add things to a profile or create a new profile. You -may also create a "clone" of an existing profile if you only wish to change a -few items but don't wish to enter all the information again. To do that, click -on the profile you want to clone and choose "Clone this profile" -there.<br><br>In the list of your profiles, you can also choose the contacts who -can see a specific profile. Just click on "Edit visibility" next to the profile -in question (only available for the profiles that are not your default profile) -and then click on user images to add them to or remove them from the group of -people who can see this profile.<br><br>Once a profile has been selected, when -the person views your profile, they will see the private profile you have -assigned. If they are not authenticated, they will see your public -profile.<br><br>There is a setting which allows you to publish your profile to a -directory and ensure that it can be found by others. You can change this setting -on the "Settings" page.<br><br>If you do not wish to be found be people unless -you give them your channel address, you may leave your profile -unpublished.<br><br><strong>Keywords and Directory Search</strong><br><br>On the -directory page, you may search for people with published profiles. Currently, -only the name field and the keywords are searched. You may also -include such keywords in your default profile - which may be used to search for -common interests with other members. Keywords are used in the channel suggestion -tool and although they aren't visible in the directory, they are shown if people -visit your profile page.<br><br>On your Connnections page and in the directory -there is a link to "Suggestions" or "Channel Suggestions", respectively. This -will find channels who have matching and/or similar keywords. The more keywords -you provide, the more relevant the search results that are returned. These are -sorted by relevance.<br><br>See Also<br><br><a class="zrl" -href="[baseurl]/help/AdvancedSearch">Advanced Searching</a> - -<h1 id="Channels">Channels</h1> -<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".<br><br>The most important features for -a channel that represents "me" are:<br><ul class="listbullet" -style="list-style-type: circle;"><br><li>Secure and private "spam free" -communications<br><br></li><li>Identity and "single-signon" across the entire -network<br><br></li><li>Privacy controls and permissions which extend to the -entire network<br><br></li><li>Directory services (like a phone -book)<br></li></ul><br>In short, a channel that represents yourself is "me, on -the internet".<br><br><h3>Creating channels</h3><br><br>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.<br><br>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.<br><br>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.<br><br>Once you have done this, your channel is ready to use. At -[observer=1]<a -href="[observer.url]">[observer.url]</a>[/observer][observer=0]example.com/ -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.<br><br><h3>The grid, permissions and delegation</h3><br><br>The "Grid" -page contains all recent posts from across Hubzilla 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.<br><br>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 <a class="zrl" -href="[baseurl]/help/roles">permissions section</a>.<br><br>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 id="roles">Account Permission Roles</h1> - -<h2>Social</h2> - -<p><strong>Mostly Public</strong></p> - -<p>The channel is a typical social networking profile. By default posts and published items are public, but one can over-ride this when creating the item and restrict it. You are listed in the directory. Your online presence and connections are visible to others.</p> - -<p><strong>Restricted</strong></p> - -<p>By default all posts and published items are sent to your 'Friends' privacy group and not made public. New friends are added to this privacy group. You can over-ride this and create a public post or published item if you desire. You are listed in the directory. Your online presence (for chat) and your connections (friends) are visible to your profile viewers.</p> - -<p><strong>Private</strong></p> - -<p>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.</p> - -<h2>Forum</h2> - -<p><strong>Mostly Public</strong></p> - -<p>The channel is a typical forum. By default posts and published items are public. Members may post by @mention+ or wall-to-wall post. Posting photos and other published items is blocked. The channel is visible in the directory. Members are added automatically.</p> - -<p><strong>Restricted</strong></p> - -<p>By default all posts and published items are sent to the channel's 'Friends' privacy group. New friends are added to this privacy group. Members may post by @mention+ or wall-to-wall post, but posts and replies may also be seen by other receipients of the top-level post who are not members. The channel is visible in the directory. Members must be manually added by the forum owner.</p> - -<p><strong>Private</strong></p> - -<p>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.</p> - -<h2>Feed</h2> - -<p><strong>Public</strong></p> - -<p>Similiar to Social - Mostly Public, but tailored for RSS feed sources. Items may be freely republished and sourced. Online presence is meaningless, therefore hidden. New connections are automatically approved.</p> - -<p><strong>Restricted</strong></p> - -<p>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.</p> - -<h2>Special</h2> - -<p><strong>Celebrity/Soapbox</strong></p> - -<p>Listed in directory. Communications are by default public. Online presence is hidden. No commenting or feedback of any form is allowed, though connections have the ability to "like" your profile.</p> - -<p><strong>Group Repository</strong></p> - -<p>A public forum which allows members to post files/photos/webpages.</p> - -<h2>Custom/Expert Mode</h2> - -<p>Set all the privacy and permissions manually to suit your specific needs.</p> - - -<h1 id="connecting-to-channels">Connecting To Channels</h1> - -<p>Connections in Hubzilla 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?</p> - -<p>First, you need to find some channels to connect to. There are two primary ways of doing this. Firstly, setting the "Can send me their channel stream and posts" permission to "Anybody in this network" will bring posts from complete strangers to your matrix. This will give you a lot of public content and should hopefully help you find interesting, entertaing people, forums, and channels.</p> - -<p>The next thing you can do is look at the Directory. The directory is available on every Hubzilla website which means searching from your own site will bring in results from the entire network. You can search by name, interest, location and keyword. This is incomplete, so we'll improve this paragraph later.</p> - -<p>To connect with other Hubzilla channels:</p> - -<p>Visit their profile by clicking their photograph in the directory, matrix, or comments, and it will open their channel home page in the channel viewer. At the left hand side of the screen, you will usually see a link called "connect". Click it, and you're done. Depending on the settings of the channel you are connecting to, you may need to wait for them to approve your connection, but no further action is needed on your part. Once you've initiated the connection, you will be taken to the connection editor. This allows you to assign specific permissions for this channel. If you don't allow any permissions, communication will be very limited. There are some quick links which you can use to avoid setting individual permissions. To provide a social network environment, "Full Sharing" is recommended. You may review the settings that are applied with the quick links to ensure they are suitable for the channel you are connecting with and adjust if necessary. Then scroll to the bottom of the page and click "Submit".</p> - -<p>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.</p> - -<h2>Block/Ignore/Archive/Hide channels</h2> - -<p>Channels in your address book can have statuses such as <em>blocked</em>, <em>ignored</em>, <em>archived</em> and <em>hidden</em>. 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.</p> - -<p>Here's their meaning:</p> - -<p><strong>Blocked:</strong> the channel can't read your items regardless of permissions, nor can it write to your channel.</p> - -<p><strong>Ignored:</strong> the channel can read your items if it has permission, but can't write to your channel.</p> - -<p><strong>Hidden:</strong> the channel does not show up in your profile's connections list, noone can see you're connected, but beware they may still show up to your other connections, for example in post replies.</p> - -<p><strong>Archived:</strong> 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.</p> - -<h2>Premium Channels</h2> - -<p>Some channels are designated "Premium Channels" and <strong>may</strong> 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 <strong>may</strong> 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.</p> - - -<h1 id="permissions">Permissions and Access Control</h1> - -<br>Permissions in Hubzilla 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.<br><br><strong>Permission Roles</strong><br><br>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. <br><br><br><strong>Default Permission Limits</strong><br><br>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, <strong>all</strong> of your photos will now be visible only to friends.<br><br><strong>Access Control</strong><br> <br>Access Control is the preferred method of managing privacy in <em>most</em> 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. <br><br>We highly recommend that you use the "typical social network" settings when you create your first channel, as it allows others to communicate with you and help you out if you have difficulty. You will find that these settings allow you as much privacy as you desire - when you desire it; but also allow you to communicate in public if you choose to. You are free to use much more private settings once you have learned your way around.<br><br><br><dl class="bb-dl dl-terms-large"> -<dt> The scopes of permissions are:</dt><dd><br><dl class="bb-dl dl-terms-italic"> -<dt> Nobody Except Yourself </dt><dd> This is self explanatory. Only you will be allowed access.<br> <br></dd> -<dt> Only those you specifically allow </dt><dd> By default, people you are not connected to, and all new contacts will have this permission denied. You will be able to make exceptions for individual channels on their contact edit screen.<br> <br></dd> -<dt> Anybody in your address book </dt><dd> Anybody you do not know will have this permission denied, but anybody you accept as a contact will have this permission approved. This is the way most legacy platforms handle permissions.<br> <br></dd> -<dt> Anybody On This Hub </dt><dd> Anybody with a channel on the same hub/website as you will have permission approved. Anybody who is registered at a different hub will have this permission denied.<br> <br></dd> -<dt> Anybody in this network </dt><dd> Anybody in Hubzilla will have this permission approved. Even complete strangers. However, anybody not logged in/authenticated will have this permission denied.<br> <br></dd> -<dt> Anybody authenticated </dt><dd> This is similar to "anybody in this network" except that it can include anybody who can authenticate by any means - and therefore <em>may</em> include visitors from other networks.<br> <br></dd> -<dt> Anybody on the internet </dt><dd> Completely public. This permission will be approved for anybody at all.<br></dd></dl><br></dd> -<dt> The individual permissions are:</dt><dd><br><dl class="bb-dl dl-terms-italic"> -<dt> Can view my "public" stream and posts. </dt><dd> This permision determines who can view your channel "stream" that is, the non-private posts that appear on the "home" tab when you're logged in.<br><br></dd> -<dt> Can view my "public" channel profile. </dt><dd> This permission determines who can view your channel's profile. This refers to the "about" tab<br><br></dd> -<dt> Can view my "public" photo albums. </dt><dd> This permission determines who can view your photo albums. Individual photographs may still be posted to a more private audience.<br><br></dd> -<dt> Can view my "public" address book. </dt><dd> This permission determines who can view your contacts. These are the connections displayed in the "View connections" section.<br><br></dd> -<dt> Can view my "public" file storage. </dt><dd> This permission determines who can view your public files stored in your cloud.<br><br></dd> -<dt> Can view my "public" pages. </dt><dd> This permission determines who can view your public web pages. <br><br></dd> -<dt> Can send me their channel stream and posts. </dt><dd> This permission determines whose posts you will view. If your channel is a personal channel (ie, you as a person), you would probably want to set this to "anyone in my address book" at a minimum. A personal notes channel would probably want to choose "nobody except myself". Setting this to "Anybody in the network" will show you posts from complete strangers, which is a good form of discovery.<br><br></dd> -<dt> Can post on my channel page ("wall"). </dt><dd> This permission determines who can write to your wall when clicking through to your channel.<br><br></dd> -<dt> Can comment on my posts. </dt><dd> This permission determines who can comment on posts you create. Normally, you would want this to match your "can view my public stream and posts" permission<br><br></dd> -<dt> Can send me private mail messages. </dt><dd> This determines who can send you private messages (zotmail).<br><br></dd> -<dt> Can post photos to my photo albums. </dt><dd> This determines who can post photographs in your albums. This is very useful for forum-like channels where connections may not be connected to each other.<br><br></dd> -<dt> Can forward to all my channel contacts via post tags. </dt><dd> Using @- mentions will reproduce a copy of your post on the profile specified, as though you posted on the channel wall. This determines if people can post to your channel in this way.<br><br></dd> -<dt> Can chat with me (when available). </dt><dd> This determines who can join the public chat rooms created by your channel.<br><br></dd> -<dt> Can write to my "public" file storage. </dt><dd> This determines who can upload files to your public file storage, or 'cloud'.<br><br></dd> -<dt> Can edit my "public" pages. </dt><dd> This determines who can edit your webpages. This is useful for wikis or sites with multiple editors.<br><br></dd> -<dt> Can administer my channel resources. </dt><dd> This determines who can have full control of your channel. This should normally be set to "nobody except myself".<br></dd></dl></dd></dl><br><em>Note:</em><br>Plugins/addons may provide special permission settings, so you may be offered additional permission settings beyond what is described here.<br><br>If you have set any of these permissions to "only those I specifically allow", you may specify indivudal permissions on the connnection edit screen.<br><br><strong>Affinity</strong><br><br>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.<br><br>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 id="cloud-storage">Cloud Storage</h1> - -<br><br>Hubzilla provides an ability to store privately and/or share arbitrary -files with friends.<br><br>You may either upload files from your computer into -your storage area, or copy them directly from the operating system using the -WebDAV protocol.<br><br>On many public servers there may be limits on disk -usage.<br><br><strong>File Attachments</strong><br><br>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.<br><br>To -delete attachments or change the permissions on the stored files, visit <a -href="[baseurl]/cloud/">[baseurl]/cloud/</a>[observer.webname]".<br><br><strong>Web -Access</strong><br><br>Your files are visible on the web at the location -"cloud/[observer.webname]" 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.<br><br><strong>WebDAV access</strong><br><br>See: <a -class="zrl" href="/help/member/member_guide#cloud-storage-clients">Cloud Desktop -Clients</a><br><br><strong>Permissions</strong><br><br>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 -"filestorage/[observer.webname]"; 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 id="cloud-storage-clients">Cloud Desktop Clients</h2> - -<h3>Windows Clients</h3> - -<h4>Windows Internal Client</h4> - -RedDav using -Windows 7 graphical user interface wizard:<br>1. Left-click the Start-button to -open the start menu.<br>2. Right-click the My computer icon to access its -menu.<br>3. Left-click Map network drive... to open the connection dialog -wizard.<br>4. Type <span class="bookmark-identifier">#^</span><a -class="bookmark" -href="https://example.net/dav/your_channel_name">https://example.net/dav/ -your_channel_name</a> in the textbox and click the Complete button where -"example.net" is the URL of your hub.<br>5. Type your Hubzilla account's user -name. IMPORTANT - NO at-sign or domain name.<br>6. Type your Hubzilla -password - - -<h3>Linux Clients</h3> - -<h4>Mounting As A Filesystem</h4> - -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<br><br><code -class="inline-code">apt-get install davfs2</code><br><br>If you want to let -normal users mount the filesystem<br><br><code -class="inline-code">dpkg-reconfigure davfs2</code><br><br>and select "yes" at -the prompt.<br><br>Now you need to add any user you want to be able to mount dav -to the davfs2 group<br><br><code class="inline-code">usermod -aG davfs2 -<DesktopUser></code><br><br><strong>Note:</strong> on some systems the -user group may be different, i.e. - "network" <br>on Arch Linux. If in doubt, -check the davfs documentation for your <br>particular OS.<br><br>Edit -/etc/fstab<br><br><code class="inline-code">nano /etc/fstab</code><br><br> to -include your cloud directory by adding<br><br><code><br><a -href="[baseurl]/dav/">[baseurl]/dav/</a> /mount/point -davfs user,noauto,uid=<DesktopUser>,file_mode=600,dir_mode=700 0 -1<br></code><br><br>Where <a -href="[baseurl]">[baseurl]</a> 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.<br><br>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 <br><br><code class="inline-code">[baseurl]/dav/ -/home/bob/cloud davfs user,noauto,uid=bob,file_mode=600,dir_mode=700 0 -1</code><br><br>Now, create the mount point.<br><br><code -class="inline-code">mkdir /home/bob/cloud</code><br><br>and also create a -directory file to store your credentials<br><br><code class="inline-code">mkdir -/home/bob/.davfs2</code><br><br>Create a file called 'secrets'<br><br><code -class="inline-code">nano /home/bob/.davfs2/secrets</code><br><br>and add your -cloud login credentials<br><br><code><br><a -href="[baseurl]/dav">[baseurl]/dav</a> -<username> <password><br></code><br><br>Where <username> and -<password> are the username and password <em>for your -hub</em>.<br><br>Don't let this file be writeable by anyone who doesn't need it -with<br><br><code class="inline-code">chmod 600 -/home/bob/.davfs2/secrets</code><br><br>Finally, mount the drive.<br><br><code -class="inline-code">mount <a -href="[baseurl]/dav">[baseurl]/dav</a></code><br><br> -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.<br><br><strong>Troubleshooting</strong><br><br>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.<br><br><code class="inline-code">nano -/etc/davfs2/davfs2.conf</code><br><br>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. <br><br>First -step is to remove locks.<br><br>Edit the use_locks line so it reads <code -class="inline-code">use_locks 0</code>.<br><br>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 -class="inline-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.<br><br>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 -class="inline-code">cache_size 0</code> and also set file_refresh to <code -class="inline-code">file_refresh 0</code>. Unmount your filesystem, -remount your file system, and test it again.<br><br>If it <em>still</em> 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 -class="inline-code">drop_weak_etags 1</code>. Unmount and remount -your filesystem to apply the changes. - - -<h4>Dolphin</h4> -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. - - -<h4>Konqueror</h4> - -Simply visit webdavs://example.com/cloud 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. - -<h4>Nautilus</h4> - -1. Open a File browsing window (that's Nautilus)<br>2. Select File > Connect to server from the menu<br>3. Type davs://<domain_name>/dav/<your_channelname> and click Connect<br>4. You will be prompted for your channel name (same as above) and password<br>5. Your personal DAV directory will be shown in the window - -<h4>Nemo</h4> - -For (file browser) Nemo 1.8.2 under Linux Mint 15, Cinnamon 1.8.8. Nemo ist the standard file browser there.<br><br>1st way<br>type "davs://<domain_name>/dav/<your_channelname>" in the address bar.<br><br>2nd way<br>Menu > file > connect to server<br>Fill the dialog<br>- Server: hubzilla_domain_name<br>- Type: Secure WebDAV (https)<br>- Folder: /dav<br>- Username: yourchannelname<br>- Password: yourpassword<br><br>Once open you can set a bookmark. - - - -<strong>Server Notes</strong><br><br>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 id="remove-channel">Remove Channel or Account</h1> - -<br><br><strong>Remove Channel</strong><br><br>Go to the bottom of your channel -settings page or visit the URL:<br><br> <a -href="[baseurl]/removeme">[baseurl]/removeme</a> -<br><br>You will need to confirm your password and the channel you are currently -logged into will be removed. <br><br>This is irreversible.<br><br>If you have -identity clones on other hubs this only removes by default the -channel instance which exists on this hub.<br><br><strong>Remove -Account</strong><br><br>Go to the bottom of your account settings page or visit -the URL:<br><br> <a -href="[baseurl]/removeaccount">[baseurl]/removeaccount -</a><br> <br>You will need to confirm your password and -the account you are currently logged into will be removed. <br><br>This is -irreversible.<br><br>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. |