From b60a07f27050a422a89d8c7f402692fbe46ca34a Mon Sep 17 00:00:00 2001 From: Diogo Peralta Cordeiro Date: Sat, 31 Jul 2021 01:57:20 +0100 Subject: [PATCH] [DOCS][Dev] Cleanup src directory --- docs/developer/src/SUMMARY.md | 39 ++-- docs/developer/src/backups.md | 6 - .../{core/event-dispatcher.md => cache.md} | 0 docs/developer/src/core.md | 4 +- .../{internationalization.md => events.md} | 0 .../{internationalization.md => core/i18n.md} | 0 docs/developer/src/install/bin-configure.md | 6 - docs/developer/src/install/dns.md | 12 -- docs/developer/src/install/docker_shell.md | 63 ------ docs/developer/src/install/no_docker_shell.md | 197 ------------------ docs/developer/src/install/no_tls.md | 7 - docs/developer/src/install/tls.md | 33 --- docs/developer/src/installation.md | 22 -- .../{sessions_and_security.md => security.md} | 0 docs/developer/src/sms.md | 47 ----- docs/developer/src/theme.md | 23 -- docs/developer/src/upgrading.md | 5 - 17 files changed, 21 insertions(+), 443 deletions(-) delete mode 100644 docs/developer/src/backups.md rename docs/developer/src/{core/event-dispatcher.md => cache.md} (100%) rename docs/developer/src/core/{internationalization.md => events.md} (100%) rename docs/developer/src/{internationalization.md => core/i18n.md} (100%) delete mode 100644 docs/developer/src/install/bin-configure.md delete mode 100644 docs/developer/src/install/dns.md delete mode 100644 docs/developer/src/install/docker_shell.md delete mode 100644 docs/developer/src/install/no_docker_shell.md delete mode 100644 docs/developer/src/install/no_tls.md delete mode 100644 docs/developer/src/install/tls.md delete mode 100644 docs/developer/src/installation.md rename docs/developer/src/{sessions_and_security.md => security.md} (100%) delete mode 100644 docs/developer/src/sms.md delete mode 100644 docs/developer/src/theme.md delete mode 100644 docs/developer/src/upgrading.md diff --git a/docs/developer/src/SUMMARY.md b/docs/developer/src/SUMMARY.md index d6e1afe179..ea6611e497 100644 --- a/docs/developer/src/SUMMARY.md +++ b/docs/developer/src/SUMMARY.md @@ -1,35 +1,34 @@ # Summary -- [Architecture: Modules](./architecture.md) - - [Programming Style](./paradigms.md) - - [Exceptions](./exceptions.md) - - [Events](./events.md) - - [Database](./database.md) - - [Cache](./cache.md) - - [Routes and Controllers](./routes_and_controllers.md) - - [Templates](./templates.md) - - [Internationalization](./internationalization.md) - - [Log](./log.md) - - [Queues](./queues.md) - - [Files](./files.md) - - [Security](./security.md) - - [HTTP](./http.md) +- [Architecture](./architecture.md) +- [Programming Style](./paradigms.md) +- [Exceptions](./exceptions.md) +- [Events](./events.md) +- [Database](./database.md) +- [Cache](./cache.md) +- [Routes and Controllers](./routes_and_controllers.md) +- [Templates](./templates.md) +- [Internationalization](./i18n.md) +- [Log](./log.md) +- [Queue](./queue.md) +- [Files](./files.md) +- [Security](./security.md) +- [HTTP](./http.md) - [Plugins](./plugins.md) - [Configuration](./plugins/configuration.md) - [Initialization and Clean Up](./plugins/lifetime.md) - [Debugging](./debugging.md) - [Sample Plugins](./sample_plugins.md) - - [Injecting Javascript](plugins/sample_plugins/Awesomeness.md) - - [Creating a block on the sidebar](plugins/sample_plugins/Sample.md) -- [Components](./components.md) -- [Core](./core.md) + - [Injecting Javascript](./plugins/sample_plugins/Awesomeness.md) + - [Creating a block on the sidebar](./plugins/sample_plugins/Sample.md) +- [Low level](./core.md) - [Overview](./core/overview.md) - [Modules](./core/modules.md) - - [Event dispatcher](./core/event-dispatcher.md) + - [Event dispatcher](./core/events.md) - [ORM and Caching](./core/orm_and_caching.md) - [Interfaces](./core/interfaces.md) - [UI](./core/ui.md) - - [Internationalization](./core/internationalization.md) + - [Internationalization](./core/i18n.md) - [Utils](./core/util.md) - [Queues](./core/queues.md) - [Files](./core/files.md) diff --git a/docs/developer/src/backups.md b/docs/developer/src/backups.md deleted file mode 100644 index c86ea5a3f9..0000000000 --- a/docs/developer/src/backups.md +++ /dev/null @@ -1,6 +0,0 @@ -# Backups - -There is no built-in system for doing backups in GNU social. You can make -backups of a working StatusNet system by backing up the database and -the Web directory. To backup the database use mysqldump -and to backup the Web directory, try tar. diff --git a/docs/developer/src/core/event-dispatcher.md b/docs/developer/src/cache.md similarity index 100% rename from docs/developer/src/core/event-dispatcher.md rename to docs/developer/src/cache.md diff --git a/docs/developer/src/core.md b/docs/developer/src/core.md index 93bafdde9e..c557e71c98 100644 --- a/docs/developer/src/core.md +++ b/docs/developer/src/core.md @@ -6,11 +6,11 @@ to start developing third party plugins. To contribute to GNU social's core, on The `core` tries to be minimal. The essence of it being various wrappers around Symfony. It is divided in: - [Modules](./core/modules.md); -- [Event dispatcher](./core/event-dispatcher.md); +- [Event dispatcher](core/events.md); - [ORM and Caching](./core/orm_and_caching.md); - [Interfaces](./core/interfaces.md); - [UI](./core/ui.md); -- [Internationalization](./core/internationalization.md); +- [Internationalization](core/i18n.md); - [Utils](./core/util.md); - [Queues](./core/queues.md); - [Files](./core/files.md); diff --git a/docs/developer/src/core/internationalization.md b/docs/developer/src/core/events.md similarity index 100% rename from docs/developer/src/core/internationalization.md rename to docs/developer/src/core/events.md diff --git a/docs/developer/src/internationalization.md b/docs/developer/src/core/i18n.md similarity index 100% rename from docs/developer/src/internationalization.md rename to docs/developer/src/core/i18n.md diff --git a/docs/developer/src/install/bin-configure.md b/docs/developer/src/install/bin-configure.md deleted file mode 100644 index 17fa6592e9..0000000000 --- a/docs/developer/src/install/bin-configure.md +++ /dev/null @@ -1,6 +0,0 @@ -TODO more detail - -Run the `bin/configure` script and enter the information as asked. - -This will generate all the required `.env` files and (optionally) a -`docker-compose.yaml` file. diff --git a/docs/developer/src/install/dns.md b/docs/developer/src/install/dns.md deleted file mode 100644 index c76607da05..0000000000 --- a/docs/developer/src/install/dns.md +++ /dev/null @@ -1,12 +0,0 @@ -### Configuring DNS - -In order for your GNU social node to be accessible with your chosen -hostname, you can create an `A` or `AAAA` DNS record, with your -server's fixed IP v4 or v6 respectively in your DNS provider -(normally, your domain registrar); the `A` record doesn't need to be -at the root of your domain, meaning it's name can be a subdomain. For -dynamic IPs, create a `CNAME` record pointing to the hostname you -created with your chosen Dynamic DNS host. A `CNAME` cannot normally be created -for a domain root, so you must use a subdomain. Note that some DNS -providers provide 'CNAME flattening', in which case you can use your -root domain. diff --git a/docs/developer/src/install/docker_shell.md b/docs/developer/src/install/docker_shell.md deleted file mode 100644 index 0f00aaae22..0000000000 --- a/docs/developer/src/install/docker_shell.md +++ /dev/null @@ -1,63 +0,0 @@ -# Docker Installation - -## Installation with Docker - -This installation method requires -[Docker](https://docs.docker.com/engine/install/) and [Docker -Compose](https://docs.docker.com/compose/install/). Use -`bin/configure` and pick `docker`, which enables all needed services -as containers, or `mixed` which lets you pick which services you'd -like to create containers for. This way you can use services in the -host machine, which may be useful if your host already has a -webserver, for instance. - -If you elect to not use some service containers, check [Instal without -Docker with shell access](./install/no_docker_shell.md) for details on -the configuration of each service. - -Please remember that for the installation `configure` script to use docker, -it is necessary that the executing user is in the docker group. - -## Prerequisites - -In order to host your GNU social instance, you'll need a domain: - - DNS domain - - `docker` - - `docker-compose` - -If you don't have a fixed public IP, for local hosting or development, -or if you're behind a NAT, use a dynamic DNS solutions. Search for -`GnuDIP host` or `dynamic dns`. To use GnuDIP, [clone](https://notabug.org/someonewithpc/gnudip.git), then inspect and run -the `./install.sh` script. This allows you to have a domain that -dynamically points to your IP address. - -If you want to install locally for development or experimenting purposes, -you can use `localhost` as the `root domain` while configuring the installation. -If you then specify a subdomain, don't forget to add it in the `/etc/hosts` file. - -{{#include dns.md}} - -{{#include tls.md}} - -{{#include no_tls.md}} - -## Configuration - -{{#include bin-configure.md}} - -## Permissions - -The PHP docker container needs the GNU social folder to be owned by -the group 82 (www-data). - -## Running - -If you elected to use all or some containers, run `docker-compose up` -from the root of the project (the folder where the `.git` folder is). -In this form, the application can be stopped by pressing `C-c` (`^C`, -`CTRL + C`); pressing it again will force the containers to stop -immediately. However, this form will show you all logs, but in most -cases, you won't want to see those all the time. For that, run -`docker-compose up -d` from the same directory; The application can -then be stopped with `docker-compose down`. - diff --git a/docs/developer/src/install/no_docker_shell.md b/docs/developer/src/install/no_docker_shell.md deleted file mode 100644 index 2ca9eb0e73..0000000000 --- a/docs/developer/src/install/no_docker_shell.md +++ /dev/null @@ -1,197 +0,0 @@ -# No Docker and shell installation - -## Prerequisites - -The following software packages are *required* for this software to -run correctly. - - - PHP 8.0+ - - Postgres 10+/MariaDB 10.2+ - - Web server - - Mail server - -Apache, lighttpd and nginx will all work. CGI mode is recommended and -also some variant of 'suexec' (or a properly setup php-fpm pool) -NOTE: mod_rewrite or its equivalent is extremely useful. - -The mail server is used for sending notifications and password resets, -among other things. - -### PHP modules - -Your PHP installation must include the following PHP extensions for a -functional setup of GNU social: - - - bcmath Arbitrary Precision Mathematics - - ctype Locale support - - curl Fetching files by HTTP. - - exif Exchangeable image information. - - gd Image manipulation (scaling). - - gmp For Salmon signatures (part of OStatus) - - iconv Locale support - - intl Internationalization support (transliteration et al). - - json For WebFinger lookups and more. - - mbstring String manipulation - - mysql The native driver for MariaDB connections. - - opcache Improved PHP performance by precompilation - - openssl (compiled in for Debian, enabled manually in Arch Linux) - - pcre Perl Compatible Regular Expression - - readline For interactive scripts - - Session User sessions - - SimpleXML XML parser - - Tokenizer Reflection and annotations - -NOTE: Some distros require manual enabling in the relevant php.ini for -some modules, even if they're included in the main PHP package. - -#### Better performance - -For some functionality, you will also need the following extensions: - - - opcache Improves performance a _lot_. Included in PHP, must be - enabled manually in php.ini for most distributions. Find - and set at least: opcache.enable=1 - - mailparse Efficient parsing of email requires this extension. - Submission by email or SMS-over-email uses this. - - sphinx A client for the sphinx server, an alternative to MySQL - or Postgresql fulltext search. You will also need a - Sphinx server to serve the search queries. - - gettext For multiple languages. Default on many PHP installs; - will be emulated if not present. - - exif For thumbnails to be properly oriented. - -You may also experience better performance from your site if you configure -a PHP cache/accelerator. Most distributions come with "opcache" support. -Enable it in your php.ini where it is documented together with its settings. - -{{#include dns.md}} - -{{#include tls.md}} - -{{#include no_tls.md}} - -### Getting it up and running - -Installing the basic GNU Social web component is relatively easy, -especially if you've previously installed PHP packages. - - 1. Download and unpack the release tarball or clone the `git` repository on - your Web server. Usually a command like this will work: - - ``` - tar zxf gnusocial-*.tar.gz - ``` - - ...which will make a `gnusocial-x.y.z` directory in your current directory. - (If you don't have shell access on your Web server, you may have to unpack - the tarball on your local computer and FTP the files to the server. Checkout - [Instal without Docker with only web access](./install/no_docker_web.md)) - - 2. Move the tarball to a directory of your choosing in your Web root - directory. Usually something like this will work: - - ``` - mv gnusocial-x.y.z /var/www/gnusocial - ``` - - This will often make your GNU social instance available in the gnusocial - path of your server, like "http://example.net/gnusocial". "social" or - "blog" might also be good path names. If you know how to configure - virtual hosts on your web server, you can try setting up - "http://social.example.net/" or the like. - - You need "rewrite" support on your webserver. This is used for "Fancy URL" - support, which you can read more about further down in this - document. - - 3. Make your target directory writeable by the Web server, please note however - that 'a+w' will give _all_ users write access and securing the webserver is - not within the scope of this document, but reading more on this subject is - recommended. - - ``` - chmod a+w /var/www/gnusocial/ - ``` - - On some systems, this will work as a more secure alternative: - - ``` - chgrp www-data /var/www/gnusocial/ - chmod g+w /var/www/gnusocial/ - ``` - - If your Web server runs as another user besides "www-data", try - that user's default group instead. As a last resort, you can create - a new group like "gnusocial" and add the Web server's user to the group. - - 4. Create a database to hold your site data. Something like this - should work (you will be prompted for your database password): - - ``` - mysqladmin -u "root" -p create social - ``` - - Note that GNU social should have its own database; you should not share - the database with another program. You can name it whatever you want, - though. - - (If you don't have shell access to your server, you may need to use - a tool like phpMyAdmin to create a database. Check your hosting - service's documentation for how to create a new database.) - - 5. Create a new database account that GNU social will use to access the - database. If you have shell access, this will probably work from the - MariaDB/PostgreSQL shell: - - GRANT ALL on social.* - TO 'social'@'localhost' - IDENTIFIED BY 'agoodpassword'; - - You should change the user identifier 'social' and 'agoodpassword' - to your preferred new database username and password. You may want to - test logging in to MariaDB/PostgreSQL as this new user. - - 6. Run `bin/configure` - -{{#include bin-configure.md}} - - 7. You should now be able to navigate to your social site's main directory - and see the "Public Timeline", which will probably be empty. You can - now register new user, post some notices, edit your profile, etc. - -### Fancy URLs - -By default, GNU social will use URLs that include the main PHP program's -name in them. For example, a user's home profile might be found at either -of these URLS depending on the webserver's configuration and capabilities: - - https://social.example.net/index.php/fred - https://social.example.net/index.php?p=fred - -It's possible to configure the software to use fancy URLs so it looks like -this instead: - - https://social.example.net/fred - -These "fancy URLs" are more readable and memorable for users. To use -fancy URLs, you must either have Apache 2.x with .htaccess enabled and -mod_rewrite enabled, -OR- know how to configure "url redirection" in -your server (like lighttpd or nginx). - -TODO Add webserver sample configs - -1. See the instructions for each respective webserver software - - - For Apache, inspect the `docs/webserver/htaccess.sample` file and save it as - `.htaccess` after making any necessary modifications. Our sample - file is well commented. - - For lighttpd, inspect the `docs/webserver/lighttpd.conf.example` file and apply the - appropriate changes in your virtualhost configuration for lighttpd. - - For nginx, inspect the `docs/webserver/nginx.conf.sample` file and apply the appropriate - changes. - - For other webservers, we gladly accept contributions of - server configuration examples. - -2. Ensure your webserver is properly configured and has its settings -applied (remember to reload/restart it) - diff --git a/docs/developer/src/install/no_tls.md b/docs/developer/src/install/no_tls.md deleted file mode 100644 index 2f78d16120..0000000000 --- a/docs/developer/src/install/no_tls.md +++ /dev/null @@ -1,7 +0,0 @@ -## Without TLS/SSL - -This is not recommended unless you know what you're doing. One -exception is if you want your node to be used with the Tor network. - -Pick 'mixed' and uncheck the `certbot` service -to disable it, or `external`, if not using docker. diff --git a/docs/developer/src/install/tls.md b/docs/developer/src/install/tls.md deleted file mode 100644 index be15f4abc5..0000000000 --- a/docs/developer/src/install/tls.md +++ /dev/null @@ -1,33 +0,0 @@ -## Configuring TLS/SSL - -You should configure a valid certificate and use TLS/SSL in most cases, -one exception being wanting to use the Tor network. - -The `bin/configure` script is capable of setting this up for you if you use a -Docker container. Otherwise, using [certbot](https://certbot.eff.org/) and -[Let's Encrypt](https://letsencrypt.org/) is recommended - -There are multiple approaches to achieve this, among which are using -your own (non-self) signed certificate, or using a proxy service -capable of either proxying an HTTP connection to HTTPS (not -recommended) or an HTTPS connection to HTTPS. For this approach, -follow the instructions of your proxy service provider, but generally -you'll use a self signed certificate, which the configuration script -can generate. - -TODO Mail server configuration (links below) - -GNU social can be configured to send emails for various reasons. See -[mail server configuration](). You'll need a certificate for your web -domain and your mail domain, which may or may not be the same (if you -use the same hostname for both, or a certificate valid for both). - -TODO improve external certificate handling - -If you prefer to not use Let's Encrypt, or the docker container, pick -`mixed` and uncheck the `certbot` service or pick `external`. - -Place your certificate in the folder -`docker/certbot/.files/live/$HOSTNAME/`, where `$HOSTNAME` is the name -where you want to host your node, such as `social.yourdomain`. -Remember you also need a certificate for your mail server. diff --git a/docs/developer/src/installation.md b/docs/developer/src/installation.md deleted file mode 100644 index d7c5de2ab3..0000000000 --- a/docs/developer/src/installation.md +++ /dev/null @@ -1,22 +0,0 @@ -# Installation - -GNU social is intended to be easily installable in both a shared hosting environment or a private -host with shell access, or just with PHP execution. - -If you need help, contact us on IRC on the `#social` room in freenode or XMPP at [xmpp:gnusocial@conference.bka.li](xmpp:gnusocial@conference.bka.li) - -The recommended way of installing is to use [Docker](https://www.docker.com/), as this simplifies -configuration. GNU social is comprised of a variety of different services, such as a webserver, a -PHP execution environment, a database, etc. You may choose to use all, some, or none of these -services in Docker containers. - -Pick one of the following installation methods: - - - [Instal with Docker with shell access](./install/docker_shell.md) - - [Instal without Docker with shell access](./install/no_docker_shell.md) - - [Instal with Docker with web access](./install/docker_web.md) (requires access to PHP's `system()`, which may be disabled) - - [Instal without Docker with only web access](./install/no_docker_web.md) - -Installation with Docker without shell access, such as in some shared hosting environments is -possible by configuring social locally and copying the files over, however this is not a supported -configuration. \ No newline at end of file diff --git a/docs/developer/src/sessions_and_security.md b/docs/developer/src/security.md similarity index 100% rename from docs/developer/src/sessions_and_security.md rename to docs/developer/src/security.md diff --git a/docs/developer/src/sms.md b/docs/developer/src/sms.md deleted file mode 100644 index 04b6ed3351..0000000000 --- a/docs/developer/src/sms.md +++ /dev/null @@ -1,47 +0,0 @@ -### SMS - -StatusNet supports a cheap-and-dirty system for sending update messages -to mobile phones and for receiving updates from the mobile. Instead of -sending through the SMS network itself, which is costly and requires -buy-in from the wireless carriers, it simply piggybacks on the email -gateways that many carriers provide to their customers. So, SMS -configuration is essentially email configuration. - -Each user sends to a made-up email address, which they keep a secret. -Incoming email that is "From" the user's SMS email address, and "To" -the users' secret email address on the site's domain, will be -converted to a notice and stored in the DB. - -For this to work, there *must* be a domain or sub-domain for which all -(or most) incoming email can pass through the incoming mail filter. - -1. Run the SQL script carrier.sql in your StatusNet database. This will - usually work: - - mysql -u "statusnetuser" --password="statusnetpassword" statusnet < db/carrier.sql - - This will populate your database with a list of wireless carriers - that support email SMS gateways. - -2. Make sure the maildaemon.php file is executable: - - chmod +x scripts/maildaemon.php - - Note that "daemon" is kind of a misnomer here; the script is more - of a filter than a daemon. - -2. Edit /etc/aliases on your mail server and add the following line: - - *: /path/to/statusnet/scripts/maildaemon.php - -3. Run whatever code you need to to update your aliases database. For - many mail servers (Postfix, Exim, Sendmail), this should work: - - newaliases - - You may need to restart your mail server for the new database to - take effect. - -4. Set the following in your config.php file: - - $config['mail']['domain'] = 'yourdomain.example.net'; diff --git a/docs/developer/src/theme.md b/docs/developer/src/theme.md deleted file mode 100644 index b50525116b..0000000000 --- a/docs/developer/src/theme.md +++ /dev/null @@ -1,23 +0,0 @@ -# Themes - -As of right now, your ability change the theme is limited to CSS -stylesheets and some image files; you can't change the HTML output, -like adding or removing menu items, without the help of a plugin. - -You can choose a theme using the $config['site']['theme'] element in -the config.php file. See below for details. - -You can add your own theme by making a sub-directory of the 'theme' -subdirectory with the name of your theme. Each theme can have the -following files: - -display.css: a CSS2 file for "default" styling for all browsers. -logo.png: a logo image for the site. -default-avatar-profile.png: a 96x96 pixel image to use as the avatar for -users who don't upload their own. -default-avatar-stream.png: Ditto, but 48x48. For streams of notices. -default-avatar-mini.png: Ditto ditto, but 24x24. For subscriptions -listing on profile pages. - -You may want to start by copying the files from the default theme to -your own directory. diff --git a/docs/developer/src/upgrading.md b/docs/developer/src/upgrading.md deleted file mode 100644 index 8c29c1cf29..0000000000 --- a/docs/developer/src/upgrading.md +++ /dev/null @@ -1,5 +0,0 @@ -# Upgrading - -Upgrading is strongly recommended to stay up to date with security fixes -and new features. For instructions on how to upgrade GNU social code, -please see the UPGRADE file.