From bf7626c8338318bfb6a176628329226b0f24e45e Mon Sep 17 00:00:00 2001 From: Leia Date: Wed, 6 Mar 2019 14:35:52 +0100 Subject: [PATCH] Add French translation --- config.toml | 30 ++ content/fr/_index.md | 15 + content/fr/administration/configuration.md | 216 ++++++++++ content/fr/administration/installation.md | 339 ++++++++++++++++ content/fr/administration/migrating.md | 98 +++++ .../fr/administration/optional-features.md | 69 ++++ .../fr/administration/post-installation.md | 106 +++++ content/fr/administration/scaling-up.md | 265 ++++++++++++ content/fr/administration/troubleshooting.md | 28 ++ content/fr/administration/upgrading.md | 57 +++ content/fr/api/authentication.md | 48 +++ content/fr/api/entities.md | 379 ++++++++++++++++++ content/fr/api/guidelines.md | 52 +++ content/fr/api/libraries.md | 102 +++++ content/fr/api/parameters.md | 44 ++ content/fr/api/permissions.md | 49 +++ content/fr/api/push.md | 15 + content/fr/api/rest/accounts.md | 203 ++++++++++ content/fr/api/rest/apps.md | 38 ++ content/fr/api/rest/blocks.md | 47 +++ content/fr/api/rest/custom-emojis.md | 17 + content/fr/api/rest/domain-blocks.md | 55 +++ content/fr/api/rest/endorsements.md | 41 ++ content/fr/api/rest/favourites.md | 43 ++ content/fr/api/rest/filters.md | 75 ++++ content/fr/api/rest/follow-requests.md | 43 ++ content/fr/api/rest/follow-suggestions.md | 25 ++ content/fr/api/rest/instances.md | 17 + content/fr/api/rest/lists.md | 127 ++++++ content/fr/api/rest/media.md | 46 +++ content/fr/api/rest/mutes.md | 73 ++++ content/fr/api/rest/notifications.md | 120 ++++++ content/fr/api/rest/polls.md | 31 ++ content/fr/api/rest/reports.md | 24 ++ content/fr/api/rest/scheduled-statuses.md | 51 +++ content/fr/api/rest/search.md | 24 ++ content/fr/api/rest/statuses.md | 177 ++++++++ content/fr/api/rest/timelines.md | 123 ++++++ content/fr/api/streaming.md | 78 ++++ content/fr/development/activitypub.md | 136 +++++++ content/fr/development/overview.md | 118 ++++++ content/fr/usage/basics.md | 68 ++++ content/fr/usage/decentralization.md | 91 +++++ content/fr/usage/moderation.md | 73 ++++ content/fr/usage/privacy.md | 75 ++++ 45 files changed, 3951 insertions(+) create mode 100644 content/fr/_index.md create mode 100644 content/fr/administration/configuration.md create mode 100644 content/fr/administration/installation.md create mode 100644 content/fr/administration/migrating.md create mode 100644 content/fr/administration/optional-features.md create mode 100644 content/fr/administration/post-installation.md create mode 100644 content/fr/administration/scaling-up.md create mode 100644 content/fr/administration/troubleshooting.md create mode 100644 content/fr/administration/upgrading.md create mode 100644 content/fr/api/authentication.md create mode 100644 content/fr/api/entities.md create mode 100644 content/fr/api/guidelines.md create mode 100644 content/fr/api/libraries.md create mode 100644 content/fr/api/parameters.md create mode 100644 content/fr/api/permissions.md create mode 100644 content/fr/api/push.md create mode 100644 content/fr/api/rest/accounts.md create mode 100644 content/fr/api/rest/apps.md create mode 100644 content/fr/api/rest/blocks.md create mode 100644 content/fr/api/rest/custom-emojis.md create mode 100644 content/fr/api/rest/domain-blocks.md create mode 100644 content/fr/api/rest/endorsements.md create mode 100644 content/fr/api/rest/favourites.md create mode 100644 content/fr/api/rest/filters.md create mode 100644 content/fr/api/rest/follow-requests.md create mode 100644 content/fr/api/rest/follow-suggestions.md create mode 100644 content/fr/api/rest/instances.md create mode 100644 content/fr/api/rest/lists.md create mode 100644 content/fr/api/rest/media.md create mode 100644 content/fr/api/rest/mutes.md create mode 100644 content/fr/api/rest/notifications.md create mode 100644 content/fr/api/rest/polls.md create mode 100644 content/fr/api/rest/reports.md create mode 100644 content/fr/api/rest/scheduled-statuses.md create mode 100644 content/fr/api/rest/search.md create mode 100644 content/fr/api/rest/statuses.md create mode 100644 content/fr/api/rest/timelines.md create mode 100644 content/fr/api/streaming.md create mode 100644 content/fr/development/activitypub.md create mode 100644 content/fr/development/overview.md create mode 100644 content/fr/usage/basics.md create mode 100644 content/fr/usage/decentralization.md create mode 100644 content/fr/usage/moderation.md create mode 100644 content/fr/usage/privacy.md diff --git a/config.toml b/config.toml index 7793d973..4c98db82 100644 --- a/config.toml +++ b/config.toml @@ -17,6 +17,36 @@ enableGitInfo = true contentDir = "content/pl" languageName = "Polski" weight = 1 + [languages.fr] + contentDir = "content/fr" + languageName = "Français" + weight = 1 + [languages.fr.menu] + [[languages.fr.menu.docs]] + name = "Guide d'utilisation" + weight = 1 + identifier = "usage" + url = "/usage/" + [[languages.fr.menu.docs]] + name = "Guide d'administration" + weight = 2 + identifier = "administration" + url = "/administration/" + [[languages.fr.menu.docs]] + name = "Guide de développement" + weight = 3 + identifier = "development" + url = "/development/" + [[languages.fr.menu.docs]] + name = "Aperçu de l'API" + weight = 4 + identifier = "api" + url = "/api/" + [[languages.fr.menu.docs]] + name = "API REST" + weight = 5 + identifier = "rest-api" + url = "/api/rest/" [menu] [[menu.docs]] diff --git a/content/fr/_index.md b/content/fr/_index.md new file mode 100644 index 00000000..e850fd45 --- /dev/null +++ b/content/fr/_index.md @@ -0,0 +1,15 @@ +--- +title: Documentation de Mastodon +--- + +Bienvenue dans la documentation de Mastodon ! + +
+ {{< youtube "IPSbNdBmWKE" >}} +
+ +**Choisissez ce que vous voulez voir aujourd'hui :** + +- [Apprendre à se servir de Mastodon]({{< relref "usage/basics.md" >}}) +- [Apprendre à installer Mastodon]({{< relref "administration/installation.md" >}}) +- [Apprendre à coder une application pour Mastodon]({{< relref "api/guidelines.md" >}}) diff --git a/content/fr/administration/configuration.md b/content/fr/administration/configuration.md new file mode 100644 index 00000000..a8d3ad1c --- /dev/null +++ b/content/fr/administration/configuration.md @@ -0,0 +1,216 @@ +--- +title: Configuration +description: Vue d'ensemble des options de configuration de Mastodon +menu: + docs: + parent: administration + weight: 2 +--- + +Mastodon utilise des variables d'environnement pour sa configuration. + +Par commodité, Mastodon lit ces variables depuis un fichier texte nommé `.env.production` dans le dossier contenant Mastodon, mais elles peuvent toujours être outrepassées par un processus. Par exemple, les fichiers de service systemd peuvent lire des variables d'environnement depuis un `EnvironmentFile` ou des variables définies avec `Environment` dans le fichier de service directement, pour que vous puissiez avoir plusieurs configurations pour des services spécifiques. Ces variables peuvent aussi être définies quand Mastodon est exécuté depuis la ligne de commande. + +## Basique +### Fédération + +- `LOCAL_DOMAIN` +- `WEB_DOMAIN` +- `ALTERNATE_DOMAINS` + +### Secrets + +- `SECRET_KEY_BASE` +- `OTP_SECRET` +- `VAPID_PRIVATE_KEY` +- `VAPID_PUBLIC_KEY` + +### Déploiement + +- `RAILS_ENV` +- `RAILS_SERVE_STATIC_FILES` +- `RAILS_LOG_LEVEL` +- `TRUSTED_PROXY_IP` +- `SOCKET` +- `PORT` +- `NODE_ENV` +- `BIND` + +### Options pour l'aménagement des ressources + +- `WEB_CONCURRENCY` +- `MAX_THREADS` +- `PREPARED_STATEMENTS` +- `STREAMING_API_BASE_URL` +- `STREAMING_CLUSTER_NUM` + +## Connexion aux bases de données +### PostgreSQL + +- `DB_HOST` +- `DB_USER` +- `DB_NAME` +- `DB_PASS` +- `DB_PORT` +- `DATABASE_URL` + +### Redis + +- `REDIS_HOST` +- `REDIS_PORT` +- `REDIS_URL` +- `REDIS_NAMESPACE` +- `CACHE_REDIS_HOST` +- `CACHE_REDIS_PORT` +- `CACHE_REDIS_URL` +- `CACHE_REDIS_NAMESPACE` + +### ElasticSearch + +- `ES_ENABLED` +- `ES_HOST` +- `ES_PORT` +- `ES_PREFIX` + +### StatsD + +- `STATSD_ADDR` +- `STATSD_NAMESPACE` + +## Limites + +- `SINGLE_USER_MODE` +- `EMAIL_DOMAIN_WHITELIST` +- `DEFAULT_LOCALE` +- `MAX_SESSION_ACTIVATIONS` +- `USER_ACTIVE_DAYS` + +## E-mail + +- `SMTP_SERVER` +- `SMTP_PORT` +- `SMTP_LOGIN` +- `SMTP_PASSWORD` +- `SMTP_FROM_ADDRESS` +- `SMTP_DOMAIN` +- `SMTP_DELIVERY_METHOD` +- `SMTP_AUTH_METHOD` +- `SMTP_CA_FILE` +- `SMTP_OPENSSL_VERIFY_MODE` +- `SMTP_ENABLE_STARTTLS_AUTO` +- `SMTP_TLS` + +## Stockage distant des fichiers + +- `CDN_HOST` +- `S3_ALIAS_HOST` + +### Stockage local des fichiers + +- `PAPERCLIP_ROOT_PATH` +- `PAPERCLIP_ROOT_URL` + +### Amazon S3 et compatibles + +- `S3_ENABLED` +- `S3_BUCKET` +- `AWS_ACCESS_KEY_ID` +- `AWS_SECRET_ACCESS_KEY` +- `S3_REGION` +- `S3_PROTOCOL` +- `S3_HOSTNAME` +- `S3_ENDPOINT` +- `S3_SIGNATURE_VERSION` + +### Swift + +- `SWIFT_ENABLED` +- `SWIFT_USERNAME` +- `SWIFT_TENANT` +- `SWIFT_PASSWORD` +- `SWIFT_PROJECT_ID` +- `SWIFT_AUTH_URL` +- `SWIFT_CONTAINER` +- `SWIFT_OBJECT_URL` +- `SWIFT_REGION` +- `SWIFT_DOMAIN_NAME` +- `SWIFT_CACHE_TTL` + +## Authentification externe + +- `OAUTH_REDIRECT_AT_SIGN_IN` + +### LDAP + +- `LDAP_ENABLED` +- `LDAP_HOST` +- `LDAP_PORT` +- `LDAP_METHOD` +- `LDAP_BASE` +- `LDAP_BIND_DN` +- `LDAP_PASSWORD` +- `LDAP_UID` +- `LDAP_SEARCH_FILTER` + +### PAM + +- `PAM_ENABLED` +- `PAM_EMAIL_DOMAIN` +- `PAM_DEFAULT_SERVICE` +- `PAM_CONTROLLED_SERVICE` + +### CAS + +- `CAS_ENABLED` +- `CAS_URL` +- `CAS_HOST` +- `CAS_PORT` +- `CAS_SSL` +- `CAS_VALIDATE_URL` +- `CAS_CALLBACK_URL` +- `CAS_LOGOUT_URL` +- `CAS_LOGIN_URL` +- `CAS_UID_FIELD` +- `CAS_CA_PATH` +- `CAS_DISABLE_SSL_VERIFICATION` +- `CAS_UID_KEY` +- `CAS_NAME_KEY` +- `CAS_EMAIL_KEY` +- `CAS_NICKNAME_KEY` +- `CAS_FIRST_NAME_KEY` +- `CAS_LAST_NAME_KEY` +- `CAS_LOCATION_KEY` +- `CAS_IMAGE_KEY` +- `CAS_PHONE_KEY` + +### SAML + +- `SAML_ENABLED` +- `SAML_ACS_URL` +- `SAML_ISSUER` +- `SAML_IDP_SSO_TARGET_URL` +- `SAML_IDP_CERT` +- `SAML_IDP_CERT_FINGERPRINT` +- `SAML_NAME_IDENTIFIER_FORMAT` +- `SAML_CERT` +- `SAML_PRIVATE_KEY` +- `SAML_SECURITY_WANT_ASSERTION_SIGNED` +- `SAML_SECURITY_WANT_ASSERTION_ENCRYPTED` +- `SAML_SECURITY_ASSUME_EMAIL_IS_VERIFIED` +- `SAML_ATTRIBUTES_STATEMENTS_UID` +- `SAML_ATTRIBUTES_STATEMENTS_EMAIL` +- `SAML_ATTRIBUTES_STATEMENTS_FULL_NAME` +- `SAML_ATTRIBUTES_STATEMENTS_FIRST_NAME` +- `SAML_ATTRIBUTES_STATEMENTS_LAST_NAME` +- `SAML_UID_ATTRIBUTE` +- `SAML_ATTRIBUTES_STATEMENTS_VERIFIED` +- `SAML_ATTRIBUTES_STATEMENTS_VERIFIED_EMAIL` + +## Services cachés (Tor) + +- `http_proxy` +- `ALLOW_ACCESS_TO_HIDDEN_SERVICE` + +## Autres + +- `SKIP_POST_DEPLOYMENT_MIGRATIONS` diff --git a/content/fr/administration/installation.md b/content/fr/administration/installation.md new file mode 100644 index 00000000..4c8fe46b --- /dev/null +++ b/content/fr/administration/installation.md @@ -0,0 +1,339 @@ +--- +title: Installation +description: Comment installer Mastodon sur un serveur Ubuntu 18.04 +menu: + docs: + parent: administration + weight: 1 +--- + + + +## Configuration basique du serveur (facultatif) + +Si vous configurez une nouvelle machine, il est recommandé de la sécuriser en premier lieu. En supposant que vous utilisez **Ubuntu 18.04** : + +### Refuser les connections SSH par mot de passe (clés uniquement) + +Assurez-vous tout d'abord que vous actuellement connecté à votre serveur en utilisant une clé SSH et non avec un mot de passe, sinon vous serez bloqué. La plupart des hébergeurs supportent l'envoi d'une clé SSH publique et configurent automatiquement la connexion à l'utilisateur root sur votre nouveau serveur via votre clé. + +Ouvrez `/etc/ssh/sshd_config` et cherchez `PasswordAuthentication`. Assurez-vous que la ligne n'est pas commentée et qu'elle est réglée sur `no`. Si vous avez apporté des modifications au fichier, redémarrez sshd : + +```sh +systemctl restart ssh +``` + +### Mettre à jour le système + +```sh +apt update && apt upgrade -y +``` + +### Installer fail2ban pour bloquer les tentatives de connexion répétées + +```sh +apt install fail2ban +``` + +Ouvrez `/etc/fail2ban/jail.local` et copiez-collez ceci à l'intérieur : + +```ini +[DEFAULT] +destemail = votre@adresse_mail.ici +sendername = Fail2Ban + +[sshd] +enabled = true +port = 22 + +[sshd-ddos] +enabled = true +port = 22 +``` + +Enfin, redémarrez fail2ban : + +```sh +systemctl restart fail2ban +``` + +### Installer un pare-feu et mettre uniquement sur liste blanche les ports SSH, HTTP et HTTPS + +D'abord, installez iptables-persistent. Durant l'installation, il vous sera demandé si vous voulez conserver les directives actuelles--refusez. + +```sh +apt install -y iptables-persistent +``` + +Ouvrez `/etc/iptables/rules.v4` et copiez-collez ceci à l'intérieur : + +``` +*filter + +# Autoriser tout trafic sur la boucle locale (lo0) et refuser tout trafic vers 127/8 qui n'utilise pas lo0 +-A INPUT -i lo -j ACCEPT +-A INPUT ! -i lo -d 127.0.0.0/8 -j REJECT + +# Autoriser toutes les connexions entrantes établies +-A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT + +# Autoriser tout le trafic sortan - vous pouvez modifier cette ligne pour n'autoriser qu'un certain type de trafic +-A OUTPUT -j ACCEPT + +# Autoriser les connexions HTTP et HTTPS de n'importe où (via les ports habituels pour les sites web et SSL) +-A INPUT -p tcp --dport 80 -j ACCEPT +-A INPUT -p tcp --dport 443 -j ACCEPT + +# Autoriser les connexions SSH +# Le nombre juste après -dport doit être le même que celui défini dans sshd_config +-A INPUT -p tcp -m state --state NEW --dport 22 -j ACCEPT + +# Autoriser le ping +-A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT + +# Enregistrer les accès refusés par iptables +-A INPUT -m limit --limit 5/min -j LOG --log-prefix "iptables denied: " --log-level 7 + +# Rejeter toutes les autres connexions entrantes - par défaut, refuser tout ce qui n'est pas défini explicitement par la directive ALLOW +-A INPUT -j REJECT +-A FORWARD -j REJECT + +COMMIT +``` + +Avec iptables-persistent, cette configuration sera chargée à chaque redémarrage. Mais puisque nous n'allons pas redémarrer tout de suite, nous devons la charger manuellement pour cette fois : + +```sh +iptables-restore < /etc/iptables/rules.v4 +``` + +## Pré-requis + +- Une machine exécutant **Ubuntu 18.04** sur laquelle vous avez un accès root +- Un **nom de domaine** (ou un sous-domaine) pour l'instance Mastodon, ex. `exemple.com` +- Un service d'envoi de courriel ou autre **serveur SMTP** + +Vous exécuterez les commandes suivantes en tant qu'utilisateur root sur le serveur. Si vous n'êtes pas encore root, identifiez-vous : + +```sh +sudo -i +``` + +### Dépôts de paquets système + +Assurez-vous que curl est installé : + +```sh +apt install -y curl +``` + +#### Node.js + +```sh +curl -sL https://deb.nodesource.com/setup_8.x | bash - +``` + +#### Yarn + +```sh +curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - +echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list +``` + +### Paquets système + +```sh +apt update +apt install -y \ + imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core \ + g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc autoconf \ + bison build-essential libssl-dev libyaml-dev libreadline6-dev \ + zlib1g-dev libncurses5-dev libffi-dev libgdbm5 libgdbm-dev \ + nginx redis-server redis-tools postgresql postgresql-contrib \ + certbot yarn libidn11-dev libicu-dev libjemalloc-dev +``` + +### Installation de Ruby + +Nous utiliserons rbenv pour gérer les différentes versions de Ruby, car c'est plus facile pour récupérer les bonnes versions et se mettre à jour quand une nouvelle version est publiée. rbenv doit être installé pour qu'un seul utilisateur, nous devons donc créer le compte utilisateur que Mastodon utilisera par la suite : + +```sh +adduser --disabled-login mastodon +``` + +Nous pouvons ensuite nous identifier : + +```sh +su - mastodon +``` + +Et procéder à l'installation de rbenv et rbenv-build: + +```sh +git clone https://github.com/rbenv/rbenv.git ~/.rbenv +cd ~/.rbenv && src/configure && make -C src +echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc +echo 'eval "$(rbenv init -)"' >> ~/.bashrc +exec bash +git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build +``` + +Une fois ceci fait, nous pouvons installer la bonne version de Ruby : + +```sh +RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 2.6.1 +rbenv global 2.6.1 +``` + +La version de gem fournie par défaut avec ruby_2.6.1 est incompatible avec la dernière version de bundler, nous devons donc mettre à jour gem : + +``` +gem update --system +``` + +Nous aurons aussi besoin d'installer bundler : + +```sh +gem install bundler --no-document +``` + +Retournez sur root : + +```sh +exit +``` + +## Configuration +### Mettre en place PostgreSQL +#### Configurer pour des performances optimales (facultatif) + +Pour obtenir des performances optimales, vous pourriez utiliser [pgTune](https://pgtune.leopard.in.ua/#/) afin de générer une configuration adéquate et modifier les valeurs si nécessaire dans `/etc/postgresql/9.6/main/postgresql.conf` avant de redémarrer PostgreSQL avec `systemctl restart postgresql` + +#### Créer un utilisateur + +Vous devez créer un utilisateur PostgreSQL que Mastodon pourra utiliser. Il est plus facile de partir sur une authentification "ident" dans une configuration basique, c-à-d que l'utilisateur PostgreSQL n'a pas un mot de passe différent et peut être utilisé par l'utilisateur Linux portant le même nom. + +Accédez à l'interface PostgreSQL : + +```sh +sudo -u postgres psql +``` + +Là, exécutez ceci : + +``` +CREATE USER mastodon CREATEDB; +\q +``` + +C'est fait ! + +### Mettre en place Mastodon + +C'est le moment de télécharger le code source de Mastodon. Connectez-vous à l'utilisateur mastodon : + +```sh +su - mastodon +``` + +#### Récupérer le code + +Utilisez git pour télécharger la dernière version stable de Mastodon : + +```sh +git clone https://github.com/tootsuite/mastodon.git live && cd live +git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1) +``` + +#### Installer les dernières dépendances + +Maintenant, installez les dépendances Ruby et JavaScript : + +```sh +bundle install \ + -j$(getconf _NPROCESSORS_ONLN) \ + --deployment --without development test +yarn install --pure-lockfile +``` + +#### Générer un fichier de configuration + +Lancez l'assistant de configuration interactif : + +```sh +RAILS_ENV=production bundle exec rake mastodon:setup +``` + +L'assistant va : + +- Créer un fichier de configuration +- Compiler les ressources web +- Créer la base de données + +Le fichier de configuration est enregistré sous le nom de `.env.production`. Vous pouvez le relire et le modifier à votre guise. Référez-vous à la [page de documentation]({{< relref "configuration.md" >}}) à ce sujet. + +Nous en avons fini avec l'utilisateur mastodon, pour l'heure, passez à nouveau sur root : + +```sh +exit +``` + +### Mettre en place nginx + +Copiez le modèle de configuration pour nginx depuis le dossier contenant Mastodon : + +```sh +cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon +ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon +``` + +Modifiez `/etc/nginx/sites-available/mastodon` pour remplacer `example.com` par votre propre nom de domaine, et apportez les autres modifications que vous auriez à faire. + +Rechargez nginx pour que les modifications soient prises en compte : + +```sh +systemctl reload nginx +``` + +### Obtenir un certificat SSL + +Nous utiliserons Let's Encrypt pour obtenir un certificat SSL gratuitement : + +```sh +certbot certonly --webroot -d example.com -w /home/mastodon/live/public/ +``` + +Modifiez `/etc/nginx/sites-available/mastodon` pour dé-commenter et adapter à votre cas les lignes `ssl_certificate` et `ssl_certificate_key`. + +Enfin, rechargez nginx pour que les modifications soient prises en compte : + +```sh +systemctl reload nginx +``` + +Vous devriez pouvoir désormais visiter votre domaine dans un navigateur web et voir l'éléphant frappant l'ordinateur avec un message d'erreur. C'est parce que nous n'avons pas encore démarré le processus Mastodon. + +### Mettre en place les services systemd + +Copiez les modèles de fichiers service systemd depuis le dossier contenant Mastodon : + +```sh +cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/ +``` + +Ouvrez les fichiers et assurez-vous que le nom d'utilisateur et les chemins d'accès sont corrects : + +- `/etc/systemd/system/mastodon-web.service` +- `/etc/systemd/system/mastodon-sidekiq.service` +- `/etc/systemd/system/mastodon-streaming.service` + +Enfin, démarrez et activez les nouveaux services systemd : + +```sh +systemctl start mastodon-web mastodon-sidekiq mastodon-streaming +systemctl enable mastodon-* +``` + +Ils démarreront automatiquement à chaque redémarrage de la machine. + +**Hourra ! C'est enfin fini. Vous pouvez accéder à votre instance depuis votre navigateur !** diff --git a/content/fr/administration/migrating.md b/content/fr/administration/migrating.md new file mode 100644 index 00000000..948ab1e2 --- /dev/null +++ b/content/fr/administration/migrating.md @@ -0,0 +1,98 @@ +--- +title: Migration de serveur +description: Comment migrer une instance Mastodon sur un nouveau serveur +menu: + docs: + parent: administration + weight: 6 +--- + +Parfois, pour des raisons diverses, vous avez besoin de migrer votre instance Mastodon d'un serveur à un autre. Heureusement, ce n'est pas une opération trop complexe, même si ça peut résulter en un petit temps où l'instance n'est pas utilisable. + +**Note :** ce guide a été écrit avec l'utilisation d'Ubuntu Server en tête ; certaines opérations peuvent différer si vous utilisez un autre système d'exploitation. + +Étapes basiques +---- + +1. Créez une nouvelle instance Mastodon en utilisant le [guide d'installation](/administration/installation/) (mais n'exécutez pas `mastodon:setup`). +2. Arrêtez Mastodon sur l'ancien serveur (par ex. `systemctl stop 'mastodon-*.service'`). +3. Sauvegardez et chargez la base de données PostgreSQL en suivant les instructions plus bas. +4. Copier les fichiers du dossier `system/` en suivant les instructions plus bas. (Note : si vous utilisez S3, vous pouvez passer cette étape.) +5. Copiez le fichier `.env.production`. +6. Exécutez `RAILS_ENV=production ./bin/tootctl feeds build` pour reconstruire les timelines personnelles de chaque utilisateur·ice. +7. Démarrez Mastodon sur le nouveau serveur. +8. Mettez à jour la zone DNS pour qu'elle pointe sur le nouveau serveur. +9. Mettez à jour ou copiez votre configuration Nginx, ré-exécutez LetsEncrypt si nécessaire. +10. Profitez de votre nouveau serveur ! + +Étapes détaillées +---- + +### Quelles données doivent être migrées + +Prioritairement, vous devez copier ceci : + +- Le dossier `~/live/public/system`, qui contient les photos et vidéos téléversées par les utilisateur·ice·s (si vous utilisez S3, vous n'avez pas à le faire) +- La base de données PostgreSQL (en utilisant [pg\_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html)) +- Le fichier `~/live/.env.production`, qui contient la configuration de l'instance et ses variables secrètes + +Moins important, vous voudrez probablement copier ces fichiers pour plus de commodité : + +- La configuration nginx (sous `/etc/nginx/sites-available/default`) +- Les fichiers de services systemd (`/etc/systemd/system/mastodon-*.service`), qui peuvent contenir des modifications spécifiques à votre instance +- La configuration PgBouncer dans `/etc/pgbouncer` (si vous l'utilisez) + +### Sauvegarder et charger PostgreSQL + +Au lieu d'exécuter `mastodon:setup`, on va créer une base de données PostgreSQL vide +en utilisant la base de données `template0` (qui est utile quand on restaure une sauvegarde PostgreSQL, +[comme détaillé dans la documentation de pg\_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)). + +Exécutez ceci en tant qu'utilisateur `mastodon` sur l'ancien serveur : + +```bash +pg_dump -Fc mastodon_production -f backup.dump +``` + +Copiez le fichier `backup.dump` sur le nouveau serveur, en utilisant `rsync` ou `scp`. Puis, sur le nouveau serveur, +créez une base de données vide en tant qu'utilisateur `mastodon` : + +```bash +createdb -T template0 mastodon_production +``` + +Et importez-la : + +```bash +pg_restore -U mastodon -n public --no-owner --role=mastodon \ + -d mastodon_production backup.dump +``` + +(Notez que si le nom d'utilisateur sur le nouveau serveur n'est pas `mastodon`, vous devriez changer les valeurs de +`-U` AND `--role` dans la commande juste au-dessus. C'est pas grave si le nom d'utilisateur est différent entre les deux serveurs.) + +### Copier les fichiers + +Cela va sûrement prendre du temps, et vous voudrez sûrement éviter de recopier des fichiers inutilement, utiliser `rsync` est donc recommandé. +Sur l'ancien serveur, en tant qu'utilisateur `mastodon`, faites : + +```bash +rsync -avz ~/live/public/system/ mastodon@exemple.fr:~/live/public/system/ +``` + +Vous répèterez l'opération si jamais les fichiers sur l'ancien serveur devaient changer. + +Vous devriez copier le fichier `.env.production`, qui contient des secrets nécessaires à l'instance. + +Optionnellement, vous pouvez copier les fichiers de configuration nginx, systemd, et pgbouncer, ou les réécrire de zéro. + +### Durant la migration + +Vous pouvez modifier le fichier `~/live/public/500.html` sur l'ancien serveur si vous voulez afficher un joli message d'erreur et permettre de faire savoir aux utilisateur·ice·s qu'une migration est en cours. + +Vous voudrez probablement modifier le TTL DNS pour quelque chose de plus petit (30 à 60 minutes) un jour à l'avance, la propagation DNS se fera ainsi plus rapidement quand vous aurez indiqué la nouvelle adresse IP. + +### Après la migration + +Vous pouvez aller sur [whatsmydns.net](http://whatsmydns.net/) pour voir la progression de la propagation DNS. +Pour ne pas attendre, vous pouvez toujours modifier votre propre fichier `/etc/hosts` pour pointer vers votre nouveau serveur et donc commencer à vous amuser avec avant les autres. diff --git a/content/fr/administration/optional-features.md b/content/fr/administration/optional-features.md new file mode 100644 index 00000000..47a6819f --- /dev/null +++ b/content/fr/administration/optional-features.md @@ -0,0 +1,69 @@ +--- +title: Fonctionnalités facultatives +description: Comment activer les fonctionnalités facultatives de Mastodon +menu: + docs: + parent: administration + weight: 5 +--- + +## Recherche plein-texte + +Mastodon supporte la recherche plein-texte quand ElasticSearch est disponible. La recherche plein-texte permet aux utilisateur·ice·s connecté·e·s de chercher dans leurs propres pouets, favoris et mentions. Cependant, la recherche plein-texte empêche délibérément de chercher arbitrairement dans toute la base de données. + +### Installer ElasticSearch + +ElasticSearch requiert un environnement java. Si vous n'avez pas Java d'installé, faites-le maintenant. En supposant que vous êtes connecté en `root` : + + apt install openjdk-8-jre-headless + +Ajoutez le dépôt logiciel officiel d'ElasticSearch : + + wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | apt-key add - + echo "deb https://artifacts.elastic.co/packages/6.x/apt stable main" | tee -a /etc/apt/sources.list.d/elastic-6.x.list + apt update + +Vous pouvez désormais installer ElasticSearch: + + apt install elasticsearch + +> **Avertissement de sécurité :** Par défaut, ElasticSearch est supposé se connecter à localhost uniquement, c-à-d être inaccessible depuis le réseau. Vous pouvez vérifier à quelle adresse ElasticSearch se connecte en regardant `network.host` dans le fichier `/etc/elasticsearch/elasticsearch.yml`. Considérez le fait que quiconque pouvant accéder à ElasticSearch sera en mesure de lire et de modifier n'importe quelle donnée à l'intérieur, puisqu'il n'y a pas de système d'authentification. C'est donc très important d'assurer la sécurité de la connexion. Avoir un pare-feu qui n'autorise que les ports 22, 80, et 443 est conseillé, comme expliqué dans [les instructions d'installation]({{< relref "installation.md" >}}). Si vous avez une instance répartie sur plusieurs serveurs, vous devez savoir comment sécuriser son trafic interne. + +Pour démarrer ElasticSearch: + + systemctl enable elasticsearch + systemctl start elasticsearch + +### Configurer Mastodon + +Modifiez `.env.production` pour ajouter les variables suivantes : + +```bash +ES_ENABLED=true +ES_HOST=localhost +ES_PORT=9200 +``` + +Si vous avez plusieurs instances Mastodon sur la même machine et que vous prévoyez d'utiliser la même installation d'ElasticSearch pour chacune d'entre elles, assurez-vous que chaque instance a un `REDIS_NAMESPACE` unique dans leur fichier de configuration, afin de différencier les index. Si vous avez besoin de passer outre le préfixe d'un index ElasticSearch, vous pouvez directement définir `ES_PREFIX`. + +Après avoir sauvegardé le nouveau fichier de configuration, créez l'index dans ElasticSearch avec : + + RAILS_ENV=production bundle exec rake chewy:upgrade + +Puis, redémarrez les processus Mastodon pour que la nouvelle configuration soit prise en compte : + + systemctl restart mastodon-sidekiq + systemctl reload mastodon-web + +Désormais, les nouveaux messages seront inscrits dans l'index ElasticSearch. La dernière étape est d'importer également toutes les anciennes données. Cela peut prendre du temps : + + RAILS_ENV=production bundle exec rake chewy:sync + +## Services cachés (Tor) + +Bientôt. + +## Connexion via LDAP/PAM/CAS/SAML + +Bientôt. + diff --git a/content/fr/administration/post-installation.md b/content/fr/administration/post-installation.md new file mode 100644 index 00000000..52471cff --- /dev/null +++ b/content/fr/administration/post-installation.md @@ -0,0 +1,106 @@ +--- +title: Opérations post-installation +description: Que faire après que l'installation de Mastodon soit terminée +menu: + docs: + parent: administration + weight: 3 +--- + +## Utiliser l'interface en ligne de commande + +L'interface en ligne de commande de Mastodon réside dans un fichier exécutable nommé `tootctl`, dans le répertoire `bin`, à l'intérieur du dossier contenant Mastodon. Vous devez obligatoirement spécifier dans quel mode vous avez l'intention de l'invoquer, en spécifiant la variable d'environnement `RAILS_ENV`. Vous devez utiliser `RAILS_ENV=production`, sauf si vous êtes un·e développeur·euse qui travaillerait sur sa propre machine. Si vous êtes sûr·e que vous n'utiliserez pas d'autre mode que `production` (les autres étant `development`, `test`, ou `staging`), vous pouvez ajouter cette variable dans le fichier `.bashrc` pour plus de commodité : + +```bash +echo "export RAILS_ENV=production" >> ~/.bashrc +``` + +Si vous faites ainsi, vous n'aurez pas à spécifier la variable à chaque fois. Sinon, les invocations de `tootctl` se passent généralement ainsi, en supposant que le code source de Mastodon réside dans `/home/mastodon/live` : + +```bash +cd /home/mastodon/live +RAILS_ENV=production bin/tootctl help +``` + +## Créer un compte administrateur +### Dans le navigateur + +Après avoir s'être inscrit·e depuis le navigateur, vous devrez user de la ligne de commande pour donner à votre compte fraîchement créé les privilèges administrateur. En supposant que votre nom d'utilisateur est `alice` : + +```bash +RAILS_ENV=production bin/tootctl accounts modify alice --role admin +``` + +### Depuis la ligne de commande + +Vous pouvez créer un nouveau compte à partir de la ligne de commande. + +```bash +RAILS_ENV=production bin/tootctl accounts create \ + alice \ + --email alice@exemple.fr \ + --confirmed \ + --role admin +``` + +Un mot de passé généré aléatoirement s'affichera dans le terminal. + +## Remplir les infos de l'instance + +Après vous être connecté, allez dans les paramètres, sur la page **Paramètres du site**, dans l'onglet Administration. Bien que techniquement il n'y ait pas d'obligation de fournir d'informations, c'est une tâche considérée comme cruciale quand il s'agit d'une instance dédiée à recevoir du monde dessus. + +|Paramètre|Signification| +|-------|-------| +|Nom d'utilisateur·ice|Votre nom d'utilisateur·ice pour que les gens sachent à qui appartient l'instance| +|Adresse courriel publique|Une adresse mail pour que les gens ne pouvant se connecter, ou les gens qui voudraient se créer un compte, puissent vous contacter| +|Description de l'instance|Pourquoi avez-vous créé cette instance ? À qui est-elle destinée ? Qu'est-ce qui la rend différente ? | +|Description étendue de l'instance|Vous pouvez mettre toutes sortes d'information dedans, mais mettre un **code de conduite** est recommandé. | + +Une fois fini, appuyez sur "Enregistrer les modifications". + +## Mettre en place des sauvegardes régulières (facultatif, mais pas vraiment non plus) + +Pour toute utilisation en conditions réelles, vous devriez vous assurer de faire des sauvegardes régulières de votre instance Mastodon. + +### Vue d'ensemble + +Voici les choses qui doivent être sauvegardées par ordre d'importance : + +1. La base de données PostgreSQL +2. Les secrets du fichier `.env.production` ou son équivalent +3. Les fichiers téléversés par les utilisateur·ice·s +4. La base de données Redis + +### Types de défaillances + +Il y a deux types de défaillances que les gens vont essayer d'éviter : la défaillance du matériel, comme la corruption des données sur le disque dur ; et l'erreur humaine et logicielle, comme une suppression involontaire des données. Dans cette documentation, on ne parlera que du premier type. + +Une base de données PostgreSQL effacée ou perdue, et c'est le game over. Mastodon stocke toutes les données les plus importantes dans la base de données PostgreSQL. Si la base de données disparaît, tous les comptes, posts et abonné·e·s de votre instance disparaîtront avec. + +Si vous perdez les secrets de configuration, certaines fonctionnalités de Mastodon cesseront de fonctionner, vos utilisateur·ice·s seront déconnectés, la double authentification (2FA) sera indisponible, les notifications push ne seront plus délivrées. + +Si vous perdez les fichiers téléversés par les utilisateur·ice·s, vous perdrez les photos de profil, bannières et photos rattachés aux posts, mais Mastodon continuera de fonctionner. + +Perdre la base de données Redis est presque inoffensif : les seules données irrécupérables seront le contenu des queues Sidekiq et les retentatives planifiées de tâches qui ont échouées. Les timelines personnelles et celles des listes sont stockées dans Redis, mais elles peuvent être refaites avec `tootctl`. + +Les meilleures sauvegardes sont celles qui sont "hors-site", c-à-d des sauvegardes qui ne sont pas sur la même machine que celle où se trouve Mastodon. Si le serveur que vous utilisez prend feu et que le disque dur explose, les sauvegardes qui sont dessus ne seront pas d'une grande aide. + +### Sauvegarder les secrets + +Les secrets sont les plus simples à sauvegarder, puisqu'ils ne changent jamais. Vous n'avez qu'à sauvegarder `.env.production` dans un endroit sûr. + +### Sauvegarder PostgreSQL + +PostgreSQL encoure le risque d'avoir des données corrompues à cause d'une coupure de courant, un disque dur défectueux, et des schémas de migrations bâclés. Pour cette raison, faire une sauvegarde de temps en temps avec `pg_dump` ou `pg_dumpall` est recommandé. + +Pour des configurations nécessitant une haute disponibilité, il est possible de répliquer la base de données afin d'avoir un deuxième serveur PostgreSQL avec des données constamment à jour, prêt à être utilisé si le premier est indisponible. + +### Sauvegarder les fichiers téléversés par les utilisateur·ice·s + +Si vous utilisez un fournisseur de stockage externe comme Amazon S3, Google Cloud ou Wasabi, vous n'avez pas besoin de vous inquiétez pour les sauvegardes. Ces entreprises sont responsables des défaillances matérielles. + +Si vous stockez localement les fichiers, c'est à vous de faire des copies du volumineux dossier `public/system`, où les fichiers téléversés sont stockés par défaut. + +### Sauvegarder Redis + +Sauvegarder Redis est simple. Redis écrit régulièrement dans `/var/lib/redis/dump.rdb`, qui est le seul fichier que vous avez à récupérer. diff --git a/content/fr/administration/scaling-up.md b/content/fr/administration/scaling-up.md new file mode 100644 index 00000000..d058c86a --- /dev/null +++ b/content/fr/administration/scaling-up.md @@ -0,0 +1,265 @@ +--- +title: Amélioration des performances +description: Comment améliorer Mastodon de manière horizontale pour gérer plus de requêtes +menu: + docs: + parent: administration + weight: 4 +--- + +## Gérer la simultanéité des processus + +Mastodon possède trois types de processus : + +- Web (Puma) +- API de streaming +- Tâches de fond (Sidekiq) + +### Web (Puma) + +Le processus web sert les requêtes HTTP à durée de vie courte sur la majorité de l'application. Les variables d'environnement suivantes contrôlent ce processus : + +- `WEB_CONCURRENCY` définit le nombre de processus créés +- `MAX_THREADS` définit le nombre de threads par processus + +Les threads se partagent la mémoire RAM du processus parent. Les processus se réservent de la mémoire RAM, même s'ils peuvent en partager entre eux via le copy-on-write. Un plus grand nombre de threads va faire monter votre processeur à 100% d'utilisation plus rapidement, un plus grand nombre de processus va remplir votre RAM plus rapidement. + +Ces valeurs agissent sur le nombre de requêtes HTTP qui pourront être traitées simultanément. + +En termes de rendement, avoir plus de processus est mieux qu'avoir plus de threads. + +### API de streaming + +L'API de streaming gère les connexions HTTP et WebSocket à durée de vie longue, à travers lesquelles les clients reçoivent en temps réel les mises à jour de statuts. Les variables d'environnement suivantes contrôlent ce processus : + +- `STREAMING_CLUSTER_NUM` définit le nombre de processus créés +- `STREAMING_API_BASE_URL` définit l'URL de l'API de streaming + +Un seul processus peut gérer un nombre considérable de connexions. L'API de streaming peut être hébergée sur un sous-domaine différent si vous le voulez, par exemple pour gagner du temps lorsque nginx relaie les connexions. + +### Tâches de fond (Sidekiq) + +Beaucoup de tâches dans Mastodon sont reléguées à l'arrière-plan afin de s'assurer que les requêtes HTTP soient rapidement traitées, et pour empêcher que des requêtes HTTP abandonnées n'affectent l'exécution de ces tâches. Sidekiq est un processus unique, avec un nombre définissable de threads. + +#### Nombre de threads + +Tandis que le nombre de threads dans le processus Web a un impact sur la réactivité de l'instance Mastodon pour l'utilisateur·ice final·e, le nombre de threads alloués aux tâches de fond a un impact sur la rapidité à laquelle les posts seront envoyés de l'instance aux autres, sur le temps qu'il faudra pour qu'un courriel soit expédié, etc. + +Le nombre de threads n'est pas défini par une variable d'environnement ici, mais par un argument lors de l'invocation de Sidekiq, par exemple : + +```sh +bundle exec sidekiq -c 15 +``` + +ferait démarrer le processus sidekiq avec 15 threads. Gardez à l'esprit que chaque thread doit être en mesure de se connecter à la base de données PostgreSQL, ce qui signifie que le pool de connexions à la base de données doit être suffisamment large pour supporter tous les threads. La taille de ce pool est définie avec l'environnement de variable `DB_POOL` et doit être au moins égale au nombre de threads. + +#### Queues + +Sidekiq utilise différentes queues pour les tâches d'importance variable, où l'importance est définie par l'impact sur l'expérience utilisateur qu’aurait une queue dysfonctionnelle, par ordre décroissant. + +|Queue|Importance| +|:---:|------------| +|`default`|Toutes les tâches qui affectent les utilisateur·ice·s de l'instance| +|`push`|La délivrance de contenus aux autres instances| +|`mailers`|L'envoi des courriels| +|`pull`|La récupération de contenus depuis d'autres instances| + +Les queues par défaut et leurs priorités sont stockées dans `config/sidekiq.yml`, mais elles peuvent être outrepassées lors de l'invocation de Sidekiq via la ligne de commandes, par exemple : + +```sh +bundle exec sidekiq -q default +``` + +n'exécutera que la queue `default`. + +Sidekiq travaille d'une certaine façon avec les queues, il vérifie d'abord s'il y a des tâches à effectuer dans la première queue, et s'il n'y en a pas, il vérifie dans la queue suivante. Cela signifie que, si la première queue est pleine à craquer, les autres queues devront patienter. + +En guise de solution, il est possible de démarrer plusieurs processus Sidekiq pour assurer une vraie exécution parallèle des queues, par exemple en créant plusieurs services systemd pour Sidekiq avec différents arguments. + +## Mise en commun des transactions avec PgBouncer +### Pourquoi vous avez potentiellement besoin de PgBouncer + +Si vous commencez à manquer de connexions vers PostgreSQL (la valeur par défaut étant de 100 connexions), alors vous pourriez trouver en PgBouncer une bonne solution. Cette section détaille des pièges récurrents ainsi que des exemples de configurations optimales pour Mastodon. + +Notez que vous pouvez aller voir "PgHero" dans la partie administration de votre instance pour savoir combien de connexions à PostgreSQL sont actuellement utilisées. Habituellement, Mastodon utilise autant de connexions qu'il y a de threads dans Puma, Sidekiq et l'API de streaming réunis. + +### Installer PgBouncer + +Sur Debian et Ubuntu: + + sudo apt install pgbouncer + +### Configurer PgBouncer +#### Définir un mot de passe + +Tout d'abord, si l'utilisateur `mastodon` dans PostgreSQL n'a pas de mot de passe, vous devrez en définir un. + +Voilà comment vous pourriez redéfinir le mot de passe : + + psql -p 5432 -U mastodon mastodon_production -w + +Puis (évidemment, utilisez un autre mot de passe que le mot "password") : + + ALTER USER mastodon WITH PASSWORD 'password'; + +Puis faites `\q` pour quitter. + +#### Configurer userlist.txt + +Modifiez `/etc/pgbouncer/userlist.txt` + +Du moment que vous spécifiez un utilisateur et un mot de passe dans pgbouncer.ini plus tard, les valeurs dans userlist.txt n'ont *pas* besoin de correspondre à de vrais utilisateurs dans PostgreSQL. Vous pouvez définir arbitrairement des utilisateurs et leurs mots de passe, mais vous pouvez aussi réutiliser les "vrais" identifiants pour plus de simplicité. Ajoutez l'utilisateur `mastodon` dans le fichier `userlist.txt` : + + "mastodon" "md5d75bb2be2d7086c6148944261a00f605" + +On utilise ici le schéma MD5, où le mot de passe est juste la somme MD5 de `mot de passe + utilisateur` avec le préfixe `md5`. Par exemple, pour générer le hash avec l'utilisateur `mastodon` et le mot de passe `password`, vous pouvez faire : + +```bash +# Ubuntu, Debian, etc. +echo -n "passwordmastodon" | md5sum +# macOS, OpenBSD, etc. +md5 -s "passwordmastodon" +``` + +Et vous n'avez plus qu'à ajouter `md5` au début de la ligne. + +Vous voudrez aussi créer un administrateur `pgbouncer` afin de vous connecter à la base de données administrateur PgBouncer. Voici un exemple de fichier `userlist.txt` : + +``` +"mastodon" "md5d75bb2be2d7086c6148944261a00f605" +"pgbouncer" "md5a45753afaca0db833a6f7c7b2864b9d9" +``` + +Dans les deux cas le mot de passe est `password`. + +#### Configurer pgbouncer.ini + +Modifiez `/etc/pgbouncer/pgbouncer.ini` + +Ajoutez une ligne en dessous de `[databases]` qui liste les bases de données PostgreSQL auxquelles vous voulez vous connecter. PgBouncer utilisera ici le même utilisateur/mot de passe et le même nom de base de données pour se connecter à PostgreSQL : + +```ini +[databases] +mastodon_production = host=127.0.0.1 port=5432 dbname=mastodon_production user=mastodon password=password +``` + +Les variables `listen_addr` et `listen_port` indiquent à PgBouncer sur quelle adresse/port accepter les connexions. Ces valeurs par défaut sont convenables. + +```ini +listen_addr = 127.0.0.1 +listen_port = 6432 +``` + +Mettez `md5` comme valeur pour `auth_type` (en supposant que vous utilisez le format MD5 dans `userlist.txt`) : + +```ini +auth_type = md5 +``` + +Assurez-vous que l'utilisateur `pgbouncer` est un administrateur : + +```ini +admin_users = pgbouncer +``` + +**Ce qui suit est très important !** Le mode par défaut du pool de connexions est "par session", tandis que Mastodon utilise le mode "par transaction". Autrement dit, une connexion PostgreSQL est initiée quand une transaction est créée, et se ferme quand la transaction est terminée. Vous voudrez donc changez la valeur de la variable `pool_mode` de `session` à `transaction` : + +```ini +pool_mode = transaction +``` + +Ensuite, `max_client_conn` définit combien de connexions PgBouncer lui-même va accepter, et `default_pool_size` pose une limite sur le nombre de connexions à PostgreSQL qui pourront être initiées. (Dans PgHero, le nombre de connexions affichées correspondra à `default_pool_size` parce qu'il ignore la présence de PgBouncer.) + +Les valeurs par défaut sont bonnes pour débuter, vous pourrez toujours les augmenter plus tard : + +```ini +max_client_conn = 100 +default_pool_size = 20 +``` + +N'oubliez pas de recharger ou redémarrer PgBouncer après avoir sauvegardé vos modifications : + + sudo systemctl reload pgbouncer + +#### Vérifier que tout fonctionne + +Vous devriez être en mesure de vous connecter à PgBouncer de la même manière qu'avec PostgreSQL : + + psql -p 6432 -U mastodon mastodon_production + +Et utiliser votre mot de passe pour vous connecter. + +Vous pouvez aussi regarder les logs de PgBouncer ainsi : + + tail -f /var/log/postgresql/pgbouncer.log + +#### Configurer Mastodon afin qu'il puisse communiquer avec PgBouncer + +Dans le fichier `.env.production`, assurez-vous que la variable suivante est définie ainsi : + +```bash +PREPARED_STATEMENTS=false +``` + +Vu qu'on fait une mise en commun des transactions, on ne peut pas utiliser des déclarations prédéfinies. + +Ensuite, configurez Mastodon pour qu'il utilise le port 6432 (PgBouncer) au lieu du port 5432 (PostgreSQL) et vous devriez pouvoir utiliser votre instance par la suite : + +```bash +DB_HOST=localhost +DB_USER=mastodon +DB_NAME=mastodon_production +DB_PASS=password +DB_PORT=6432 +``` + +> **Hop hop hop !** Vous ne pouvez pas utiliser PgBouncer pour effectuer les tâches `db:migrate`. Mais il est facile de contourner le problème. Si PostgreSQL et PgBouncer sont sur la même machine, il suffit de définir `DB_PORT=5432` en plus de `RAILS_ENV=production` quand vous invoquez la tâche. Par exemple : `RAILS_ENV=production DB_PORT=5432 bundle exec rails db:migrate` (vous pouvez aussi définir `DB_HOST` si l'un des deux services n'est pas sur la même machine, etc.) + +#### Administrer PgBouncer + +La façon la plus simple de redémarrer PgBouncer est de faire ainsi : + + sudo systemctl restart pgbouncer + +Mais si vous avez créé un utilisateur avec les droits administrateurs dans PgBouncer, vous pouvez aussi vous connecter en tant qu'administrateur : + + psql -p 6432 -U pgbouncer pgbouncer + +Puis faire : + + RELOAD; + +Et enfin quitter en faisant `\q`. + +## Un Redis séparé pour le cache + +Redis est largement utilisé à travers l'application, mais certaines utilisations de Redis sont plus importantes que d'autres. Les timelines personnelles et des listes, les queues Sidekiq ainsi que l'API de streaming sont fournies par Redis et ce sont des données importantes que vous ne voudriez pas perdre (même si cette perte peut être surmontée, contrairement à celle de la base de données PostgreSQL – ne la perdez jamais !). Cependant, Redis est aussi utilisé pour le cache volatile. Si vous en êtes arrivés au stade dans l'amélioration des performances où vous avez peur que Redis ne puisse tout gérer, vous pouvez utiliser une autre base de données Redis pour le cache. Dans l'environnement d'exécution, vous pouvez spécifier la variable `CACHE_REDIS_URL` ou des variables plus restreintes comme `CACHE_REDIS_HOST`, `CACHE_REDIS_PORT`, etc. Les variables non définies auront les valeurs par défaut, celles utilisées s'il n'y avait pas de deuxième cache. + +Si vous voulez configurer la base de données Redis, vous pouvez vous débarrasser de l'écriture en arrière-plan des données sur le disque, puisque ce n'est pas très important si les données sont perdues au redémarrage, et vous pourrez ainsi économiser des accès lecture/écriture sur le disque. Vous pouvez également ajouter une limite d'utilisation de mémoire et une règle de suppression de données obsolètes, mais pour ça, il faudra lire cette page (en anglais) : [Using Redis as an LRU cache](https://redis.io/topics/lru-cache) + +## Réplication des données + +Pour réduire la charge sur votre serveur PostgreSQL, vous pourriez mettre en place une réplication des données (read replica). [Lisez ce guide pour voir un exemple](https://cloud.google.com/community/tutorials/setting-up-postgres-hot-standby). Vous pouvez utiliser la réplication dans Mastodon de différentes manières : + +- L'API de streaming ne génère pas d'écritures sur le disque, vous pouvez donc connecter l'API directement au serveur répliquant. Mais puisque l'API n’interroge pas souvent la base de données, l'impact sur les performances sera moindre. +- Utiliser Makara dans les processus Web et Sidekiq, ainsi les écritures iront sur le serveur principal tandis que les lectures iront sur le serveur répliquant. Voyons cela plus en détail. + +Vous aurez à modifier le fichier `config/database.yml` et remplacer la section `production` ainsi : + +```yml +production: + <<: *default + adapter: postgresql_makara + prepared_statements: false + makara: + id: postgres + sticky: true + connections: + - role: master + blacklist_duration: 0 + url: postgresql://db_user:db_password@db_host:db_port/db_name + - role: slave + url: postgresql://db_user:db_password@db_host:db_port/db_name +``` + +Assurez-vous que les URL pointent au bon endroit. Vous pouvez ajouter plusieurs serveurs pour répliquer les données. Vous pouvez avoir PgBouncer installé sur le serveur hébergeant Mastodon, avec une configuration connectant PgBouncer à deux serveurs PostgreSQL différents en fonction du nom de la base de données appelée, par exemple "mastodon" irait sur le serveur principal et "mastodon_replica" irait sur le répliquant. Dans le fichier ci-dessus, les deux URL pointeraient sur PgBouncer avec le même utilisateur, le même mot de passe, le même hôte et port, mais avec un nom de base de données différent. Les possibilités sont infinies ! Pour plus d'informations sur Makara, [consultez leur documentation](https://github.com/taskrabbit/makara#databaseyml). diff --git a/content/fr/administration/troubleshooting.md b/content/fr/administration/troubleshooting.md new file mode 100644 index 00000000..8243f0c9 --- /dev/null +++ b/content/fr/administration/troubleshooting.md @@ -0,0 +1,28 @@ +--- +title: Résolution de problèmes +description: Comment trouver ce qui ne va pas avec votre instance Mastodon +menu: + docs: + parent: administration + weight: 99 +--- + +**Je vois une page d'erreur qui dit que quelque chose ne s'est pas bien passé. Comment je fais pour savoir ce qui ne va pas ?** + +Tous les messages d'erreur avec des stack traces sont inscrits dans le log système. Si vous utilisez systemd, les logs de chaque service systemd peuvent être lus avec `journalctl -u mastodon-web` (remplacez avec le nom du service désiré). Si vous utilisez Docker, c'est à peu près pareil : `docker logs mastodon_web_1` (remplacez avec le nom du conteneur désiré). + +Le détail des erreurs côté serveur n'est *jamais* donné au public, puisqu'il peut révéler comment votre instance est configurée et cela peut donner aux attaquants des indices pour s'infiltrer dans le système ou mieux en abuser. + +Chaque réponse du serveur web Mastodon est accompagné d'un header avec un identifiant de requête unique, qui apparaît dans les logs. En inspectant les headers de la page d'erreur, vous pourrez facilement retrouver la stack trace correspondante dans les logs. + +**Après avoir mis à jour vers une version supérieure, quelques pages s'affichent bizarrement. Pourquoi ?** + +Vérifier que vous avez exécuté `RAILS_ENV=production bin/rails assets:precompile` après la mise à jour, et redémarré le processus web de Mastodon, puisqu'il semble que le processus envoie encore des feuilles de style et des scripts périmés. Il se peut aussi que la précompilation ait échouée à cause d'un manque de mémoire RAM, webpack prenant malheureusement beaucoup trop de mémoire. Si c'est le cas, assurez-vous d'avoir un espace swap de disponible. Sinon, il est possible de pré-compiler les ressources web sur une autre machine, et de les copier ensuite dans le dossier `public/packs`. + +**Après avoir mis à jour vers une version supérieure, certaines requêtes échouent et les logs montrent des messages d'erreurs à propos de colonnes ou tables manquantes. Pourquoi ?** + +Vérifiez que vous avez exécuté `RAILS_ENV=production bin/rails db:migrate` après la mise à jour, puisqu'il semble que votre Mastodon essaye d'accéder à un schéma de base de données plus ancien ou plus récent que prévu. Si vous utilisez PgBouncer, assurez-vous que cette commande le connecte directement à PostgreSQL, puisque PgBouncer ne supporte pas vraiment les verrouillages de tables qui sont utilisés lors des mises à jour. + +**J'essaye d'exécuter une commande `tootctl` ou `rake`/`rails`, mais tout ce que j'obtiens est une erreur à propos de constantes non initialisées. Qu'est-ce qui ne va pas ?** + +Vérifiez que vous avez mis `RAILS_ENV=production` avant le début de votre commande. Par défaut, Mastodon s'exécute dans un environnement supposé être de développement, donc il essaye de charger des gemmes Ruby liées au développement. Cependant, dans un environnement de production, on évite d'installer ces gems Ruby, et c'est de là que vient l'erreur. diff --git a/content/fr/administration/upgrading.md b/content/fr/administration/upgrading.md new file mode 100644 index 00000000..d92b0e84 --- /dev/null +++ b/content/fr/administration/upgrading.md @@ -0,0 +1,57 @@ +--- +title: Mettre à jour son instance +description: Comment mettre à jour Mastodon vers une version plus récente +menu: + docs: + parent: administration + weight: 5 +--- + +Quand une nouvelle version de Mastodon est publiée, elle apparaît sur la [page des versions sur GitHub](https://github.com/tootsuite/mastodon/releases). Notez toutefois qu'exécuter du code de la branche `master` (et donc pas prêt pour le grand public) est dans la plupart des cas non recommandé. + +Les versions de Mastodon correspondent aux étiquettes git. Tout d'abord, connectez-vous avec l'utilisateur `mastodon` : + +```sh +su - mastodon +``` + +Allez à la racine du répertoire contenant Mastodon : + +```sh +cd /home/mastodon/live +``` + +Téléchargez le code de la dernière version, en supposant ici que la dernière version se nomme `v2.5.0` : + +```sh +git fetch --tags +git checkout v2.5.0 +``` + +La page des versions contient une liste des modifications et nouveautés apportées par une version, et en dessous, les instructions pour réaliser la mise à jour (en anglais). Si la dernière version nécessite par exemple de recompiler les ressources web, vous exécuteriez cette commande : + +```sh +RAILS_ENV=production bundle exec rails assets:precompile +``` + +Après avoir exécuté toutes les instructions spécifiques à la dernière version, il ne reste plus qu'à redémarrer Mastodon. *Habituellement*, l'API de streaming n'est pas mise à jour et ne nécessite pas de redémarrage. La redémarrer pourrait causer une charge inhabituellement haute sur le serveur, il est donc conseillé d'éviter de le faire le plus possible. + +Déconnectez-vous pour retourner à l'utilisateur root : + +```sh +exit +``` + +Vous devriez redémarrer Sidekiq : + +```sh +systemctl restart mastodon-sidekiq +``` + +Et vous devriez recharger le processus web pour éviter une période d'indisponibilité de l'instance : + +```sh +systemctl reload mastodon-web +``` + +**C'est tout !** Vous utilisez désormais la dernière version de Mastodon. diff --git a/content/fr/api/authentication.md b/content/fr/api/authentication.md new file mode 100644 index 00000000..ee65649d --- /dev/null +++ b/content/fr/api/authentication.md @@ -0,0 +1,48 @@ +--- +title: Authentication +description: How to authenticate with OAuth 2 on Mastodon +menu: + docs: + parent: api + weight: 1 +--- + +Mastodon is federated, therefore you can't be expected to manually register your application on all potential servers your users might want to login on. For this reason, there is an open app registration API, so obtaining OAuth 2 credentials for OAuth 2 authorization can be automated. + +Make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to acquire a client id/secret for OAuth 2 and then proceed with normal OAuth 2 also using that domain to build the URLs. + +Mastodon supports the following OAuth 2 flows: + +- **Authorization code flow**: For end-users +- **Password grant flow**: For bots and other single-user applications +- **Client credentials flow**: For applications that do not act on behalf of users + +## OAuth 2 endpoints + +The following descriptions are taken from the [Doorkeeper documentation](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples). Mastodon uses Doorkeeper to implement OAuth 2. + +### GET /oauth/authorize + +Redirect here with `response_type=code`, `client_id`, `client_secret`, `redirect_uri`, `scope`. Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired `redirect_uri`, or show the authorization code if `urn:ietf:wg:oauth:2.0:oob` was requested. + +### POST /oauth/token + +Post here with `authorization_code` for authorization code grant type or `username` and `password` for password grant type. Returns an access token. This corresponds to the token endpoint, section 3.2 of the OAuth 2 RFC. + +### POST /oauth/revoke + +Post here with client credentials (in basic auth or in params `client_id` and `client_secret`) to revoke an access token. This corresponds to the token endpoint, using the OAuth 2.0 Token Revocation RFC (RFC 7009). + +## Example authorization code flow + +1. Get `client_id` and `client_secret` from your local cache. If you don't have the two, you need to [register the application]({{< relref "api/rest/apps.md#post-api-v1-apps" >}}). Store `client_id` and `client_secret` in your local cache for next time. We actually don't need the `id` returned from this call. +1. Tell the user to visit `/oauth/authorize` with parameters `scope`, `response_type=code`, `redirect_uri`, and your `client_id`. The user clicks on the URL and gets shown a page asking them to authorize your app for the scopes you requested. If the user clicks on the right button, they are redirected back to your `redirect_uri` with a `code` param in the query string. That is the authorization code. +1. Send a POST request to `/oauth/token` with the parameters `client_id`, `client_secret`, `grant_type=authorization_code`, `code`, `redirect_uri`. Save the `access_token` you get back in your local cache. Note that an authorization code can only be used once. If it has been used already, you need to repeat step two to get a new one. + +Once you have the access token, add the HTTP header `Authorization: Bearer ...` to any API call. + +## Common gotchas + +- The OAuth param name is `scope`, but when registering the application using Mastodon's REST API, the param name is `scopes`. The OAuth param can be a subset of the scopes you registered initially, but cannot include anything that wasn't in the original set. +- The OAuth param name is `redirect_uri`, but when registering the application using Mastodon's REST API, the param name is `redirect_uris`. The latter can actually consist of multiple allowed URIs, separated by newlines. +- The `redirect_uri` in all OAuth requests must either be the same as the one registered with the application, or one of them, if you registered multiple URIs separated by newlines with the application. \ No newline at end of file diff --git a/content/fr/api/entities.md b/content/fr/api/entities.md new file mode 100644 index 00000000..e4e8df2e --- /dev/null +++ b/content/fr/api/entities.md @@ -0,0 +1,379 @@ +--- +title: Entities +description: Overview of entities returned from Mastodon's REST API +menu: + docs: + parent: api + weight: 3 +--- + +- All IDs are encoded as string representations of integers. + - IDs can be sorted first by size, and then lexically, to produce a chronological ordering of resources. +- All datetimes are in ISO 8601 format +- All HTML strings are sanitized by the server +- All language codes are in ISO 6391 format + +## Account + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `id` | String |{{< no >}}|0.1.0| +| `username` | String |{{< no >}}|0.1.0| +| `acct` | String |{{< no >}}|0.1.0| +| `display_name` | String |{{< no >}}|0.1.0| +| `locked` | Boolean |{{< no >}}|0.1.0| +| `created_at` | String (Datetime) |{{< no >}}|0.1.0| +| `followers_count` | Number |{{< no >}}|0.1.0| +| `following_count` | Number |{{< no >}}|0.1.0| +| `statuses_count` | Number |{{< no >}}|0.1.0| +| `note` | String |{{< no >}}|0.1.0| +| `url` | String (URL) |{{< no >}}|0.1.0| +| `avatar` | String (URL) |{{< no >}}|0.1.0| +| `avatar_static` | String (URL) |{{< no >}}|1.1.2| +| `header` | String (URL) |{{< no >}}|0.1.0| +| `header_static` | String (URL) |{{< no >}}|1.1.2| +| `emojis` | Array of [Emoji](#emoji) |{{< no >}}|2.4.0| +| `moved` | [Account](#account) |{{< yes >}}|2.1.0| +| `fields` | Array of [Hash](#field) |{{< yes >}}|2.4.0| +| `bot` | Boolean |{{< yes >}}|2.4.0| + +### Field + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `name` | String |{{< no >}}|2.4.0| +| `value` | String (HTML) |{{< no >}}|2.4.0| +| `verified_at` | String (Datetime) |{{< yes >}}|2.6.0| + +### Source + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `privacy` | String |{{< yes >}}|1.5.0| +| `sensitive` | Boolean |{{< yes >}}|1.5.0| +| `language` | String (ISO6391) |{{< yes >}}|2.4.2| +| `note` | String |{{< no >}}|1.5.0| +| `fields` | Array of Hash |{{< no >}}|2.4.0| + +### Token + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `access_token` | String |{{< no >}}|0.1.0| +| `token_type` | String |{{< no >}}|0.1.0| +| `scope` | String |{{< no >}}|0.1.0| +| `created_at` | Number |{{< no >}}|0.1.0| + +## Application + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `name` | String |{{< no >}}|0.9.9| +| `website` | String (URL) |{{< yes >}}|0.9.9| + +## Attachment + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `id` | String |{{< no >}}|0.6.0| +| `type` | [String (Enum)](#type) |{{< no >}}|0.6.0| +| `url` | String (URL) |{{< no >}}|0.6.0| +| `remote_url` | String (URL) |{{< yes >}}|0.6.0| +| `preview_url` | String (URL) |{{< no >}}|0.6.0| +| `text_url` | String (URL) |{{< yes >}}|0.6.0| +| `meta` | [Hash](#meta) |{{< yes >}}|1.5.0| +| `description` | String |{{< yes >}}|2.0.0| + +### Type + +- `unknown` +- `image` +- `gifv` +- `video` + +### Meta + +May contain subtrees `small` and `original`. + +Images may contain `width`, `height`, `size`, `aspect`, while videos (including GIFV) may contain `width`, `height`, `frame_rate`, `duration` and `bitrate`. + +There may be another top-level object, `focus` with the coordinates `x` and `y`. These coordinates can be used for smart thumbnail cropping, [see this for reference](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point). + +## Card + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `url` | String (URL) |{{< no >}}|1.0.0| +| `title` | String |{{< no >}}|1.0.0| +| `description` | String |{{< no >}}|1.0.0| +| `image` | String (URL) |{{< yes >}}|1.0.0| +| `type` | [String (Enum)](#type-1) |{{< no >}}|1.3.0| +| `author_name` | String |{{< yes >}}|1.3.0| +| `author_url` | String (URL) |{{< yes >}}|1.3.0| +| `provider_name` | String |{{< yes >}}|1.3.0| +| `provider_url` | String (URL) |{{< yes >}}|1.3.0| +| `html` | String (HTML) |{{< yes >}}|1.3.0| +| `width` | Number |{{< yes >}}|1.3.0| +| `height` | Number |{{< yes >}}|1.3.0| + +### Type + +- `link` +- `photo` +- `video` +- `rich` + +## Context + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `ancestors` | Array of [Status](#status) |{{< no >}}|0.6.0| +| `descendants` | Array of [Status](#status) |{{< no >}}|0.6.0| + +## Emoji + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `shortcode` | String |{{< no >}}|2.0.0| +| `static_url` | String (URL) |{{< no >}}|2.0.0| +| `url` | String (URL) |{{< no >}}|2.0.0| +| `visible_in_picker` | Boolean |{{< no >}}|2.1.0| + +## Error + +The most important part of an error response is the HTTP status code. Standard semantics are followed. The body of an error is a JSON object with this structure: + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `error` | String |{{< no >}}|0.6.0| + +## Filter + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `id` | String |{{< no >}}|2.4.3| +| `phrase` | String |{{< no >}}|2.4.3| +| `context` | Array of [String (Enum)](#context) |{{< no >}}|2.4.3| +| `expires_at` | String (Datetime) |{{< yes >}}|2.4.3| +| `irreversible` | Boolean |{{< no >}}|2.4.3| +| `whole_word` | Boolean |{{< no >}}|2.4.3| + +### Context + +- `home` +- `notifications` +- `public` +- `thread` + +### Implementation notes + +If `whole_word` is true , client app should do: + +- Define 'word constituent character' for your app. In the official implementation, it's `[A-Za-z0-9_]` in JavaScript, and `[[:word:]]` in Ruby. In Ruby case it's the POSIX character class (Letter | Mark | Decimal_Number | Connector_Punctuation). +- If the phrase starts with a word character, and if the previous character before matched range is a word character, its matched range should be treated to not match. +- If the phrase ends with a word character, and if the next character after matched range is a word character, its matched range should be treated to not match. + +Please check `app/javascript/mastodon/selectors/index.js` and `app/lib/feed_manager.rb` in the Mastodon source code for more details. + +## Instance + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `uri` | String |{{< no >}}|1.1.0| +| `title` | String |{{< no >}}|1.1.0| +| `description` | String |{{< no >}}|1.1.0| +| `email` | String |{{< no >}}|1.1.0| +| `version` | String |{{< no >}}|1.3.0|# +| `thumbnail` | String (URL) |{{< yes >}}|1.6.1| +| `urls` | [Hash](#urls) |{{< no >}}|1.4.2| +| `stats` | [Hash](#stats) |{{< no >}}|1.6.0| +| `languages` | Array of String (ISO 639, Part 1-5) |{{< no >}}|2.3.0| +| `contact_account` | [Account](#account) |{{< yes >}}|2.3.0| + +### URLs + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +|`streaming_api`| String (URL) |{{< no >}}|1.4.2| + +### Stats + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +|`user_count`| Number |{{< no >}}|1.6.0| +|`status_count`| Number |{{< no >}}|1.6.0| +|`domain_count`| Number |{{< no >}}|1.6.0| + +## List + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `id` | String |{{< no >}}|2.1.0| +| `title` | String |{{< no >}}|2.1.0| + +## Mention + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `url` | String (URL) |{{< no >}}|0.6.0| +| `username` | String |{{< no >}}|0.6.0| +| `acct` | String |{{< no >}}|0.6.0| +| `id` | String |{{< no >}}|0.6.0| + +## Notification + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `id` | String |{{< no >}}|0.9.9| +| `type` | [String (Enum)](#type-2) |{{< no >}}|0.9.9| +| `created_at` | String (Datetime) |{{< no >}}|0.9.9| +| `account` | [Account](#account) |{{< no >}}|0.9.9| +| `status` | [Status](#status) |{{< yes >}}|0.9.9| + +### Type + +- `follow` +- `mention` +- `reblog` +- `favourite` + +## Poll + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `id` | String |{{< no >}}|2.8.0| +| `expires_at` | String (Datetime) |{{< yes >}}|2.8.0| +| `expired` | Boolean |{{< no >}}|2.8.0| +| `multiple` | Boolean |{{< no >}}|2.8.0| +| `votes_count` | Number |{{< no >}}|2.8.0| +| `options` | Array of [Poll option](#poll-option) |{{< no >}}|2.8.0| +| `voted` | Boolean |{{< yes >}}|2.8.0| + +### Poll option + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `title` | String |{{< no >}}|2.8.0| +| `votes_count` | Number |{{< yes >}}|2.8.0| + +## Push subscription + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `id` | String |{{< no >}}|2.4.0| +| `endpoint` | String (URL) |{{< no >}}|2.4.0| +| `server_key` | String |{{< no >}}|2.4.0| +| `alerts` | [Hash](#alerts) |{{< no >}}|2.4.0| + +### Alerts + +??? + +## Relationship + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `id` | String |{{< no >}}|0.6.0| +| `following` | Boolean |{{< no >}}|0.6.0| +| `followed_by` | Boolean |{{< no >}}|0.6.0| +| `blocking` | Boolean |{{< no >}}|0.6.0| +| `muting` | Boolean |{{< no >}}|1.1.0| +| `muting_notifications` | Boolean |{{< no >}}|2.1.0| +| `requested` | Boolean |{{< no >}}|0.9.9| +| `domain_blocking` | Boolean |{{< no >}}|1.4.0| +| `showing_reblogs` | Boolean |{{< no >}}|2.1.0| +| `endorsed` | Boolean |{{< no >}}|2.5.0| + +## Results + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `accounts` | Array of [Account](#account) |{{< no >}}|1.1.0| +| `statuses` | Array of [Status](#status) |{{< no >}}|1.1.0| +| `hashtags` | Array of [Tag](#tag) |{{< no >}}|1.1.0| + +## Status + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `id` | String |{{< no >}}|0.1.0| +| `uri` | String |{{< no >}}|0.1.0| +| `url` | String (URL) |{{< yes >}}|0.1.0| +| `account` | [Account](#account) |{{< no >}}|0.1.0| +| `in_reply_to_id` | String |{{< yes >}}|0.1.0| +| `in_reply_to_account_id` | String |{{< yes >}}|1.0.0| +| `reblog` | [Status](#status) |{{< yes >}}|0.1.0| +| `content` | String (HTML) |{{< no >}}|0.1.0| +| `created_at` | String (Datetime) |{{< no >}}|0.1.0| +| `emojis` | Array of [Emoji](#emoji) |{{< no >}}|2.0.0| +| `replies_count` | Number |{{< no >}}|2.5.0| +| `reblogs_count` | Number |{{< no >}}|0.1.0| +| `favourites_count` | Number |{{< no >}}|0.1.0| +| `reblogged` | Boolean |{{< yes >}}|0.1.0| +| `favourited` | Boolean |{{< yes >}}|0.1.0| +| `muted` | Boolean |{{< yes >}}|1.4.0| +| `sensitive` | Boolean |{{< no >}}|0.9.9| +| `spoiler_text` | String |{{< no >}}|1.0.0| +| `visibility` | [String (Enum)](#visibility) |{{< no >}}|0.9.9| +| `media_attachments` | Array of [Attachment](#attachment) |{{< no >}}|0.6.0| +| `mentions` | Array of [Mention](#mention) |{{< no >}}|0.6.0| +| `tags` | Array of [Tag](#tag) |{{< no >}}|0.9.0| +| `card` | [Card](#card) |{{< yes >}}|2.6.0| +| `poll` | [Poll](#poll) |{{< yes >}}|2.8.0| +| `application` | [Application](#application) |{{< no >}}|0.9.9| +| `language` | String (ISO6391) |{{< yes >}}|1.4.0| +| `pinned` | Boolean |{{< yes >}}|1.6.0| + +### Visibility + +- `public` +- `unlisted` +- `private` +- `direct` + +## ScheduledStatus + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `id` | String |{{< no >}}|2.7.0| +| `scheduled_at` | String (Datetime) |{{< no >}}|2.7.0| +| `params` | Array of [Hash](#statusparams) |{{< no >}}|2.7.0| +| `media_attachments` | Array of [Attachment](#attachment) |{{< no >}}|2.7.0| + +### StatusParams + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `text` | String |{{< no >}}|2.7.0| +| `in_reply_to_id` | String |{{< yes >}}|2.7.0| +| `media_ids` | Array of String |{{< yes >}}|2.7.0| +| `sensitive` | Boolean |{{< yes >}}|2.7.0| +| `spoiler_text` | String |{{< yes >}}|2.7.0| +| `visibility` | [String (Enum)](#visibility) |{{< no >}}|2.7.0| +| `scheduled_at` | String (Datetime) |{{< yes >}}|2.7.0| +| `application_id` | String |{{< no >}}|2.7.0| + +## Tag + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `name` | String |{{< no >}}|0.9.0| +| `url` | String (URL) |{{< no >}}|0.9.0| +| `history` | Array of [History](#history) |{{< yes >}}|2.4.1| + +### History + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `day` | String (UNIX timestamp) |{{< no >}}|2.4.1| +| `uses` | Number |{{< no >}}|2.4.1| +| `accounts` | Number |{{< no >}}|2.4.1| + +### Conversation + +|Attribute|Type|Nullable|Added in| +|---------|-----------|:------:|:------:| +| `id` | String |{{< no >}}|2.6.0| +| `accounts` | Array of [Account](#account) |{{< no >}}|2.6.0| +| `last_status` | [Status](#status) |{{< yes >}}|2.6.0| +| `unread` | Boolean |{{< no >}}|2.6.0| diff --git a/content/fr/api/guidelines.md b/content/fr/api/guidelines.md new file mode 100644 index 00000000..b9ef1ec2 --- /dev/null +++ b/content/fr/api/guidelines.md @@ -0,0 +1,52 @@ +--- +title: Guidelines +description: Guidelines that app developers for Mastodon should follow +menu: + docs: + parent: api + weight: -1 +--- + +## Login + +**The user must be able to login to any Mastodon server from the app**. This means you must ask for either the full handle, or server domain, and use the app registrations API to dynamically obtain OAuth2 credentials. + +## Usernames + +**Decentralization must be transparent to the user**. It should be possible to see that a given user is from another server, by e.g. displaying their `acct` (username and domain) somewhere. + +## Formatting + +Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**. + +### HTML tags + +You may expect these tags to appear in the content: `

`, `
`, ``, `` + +### Mentions and hashtags + +Mentions and hashtags are `` tags. To give those links their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the status, which can be matched to a particular tag. + +### Custom emoji + +Custom emoji remain in their plain text shortcode form. Metadata about the determined custom emoji is included with the status, and the shortcodes must be matched against the text to display the images. + +### Other links + +Links in Mastodon are not shortened using URL shorteners. However, URLs in text always count for 23 characters, and are intended to be shortened visually. For that purpose, a link is marked up like this: + +```html + + + example.com/page + + +``` + +The spans with the `invisible` class can be hidden. The middle span is intended to remain visible. It may have no class if the URL is not very long, otherwise it will have an `ellipsis` class. No ellipsis (`…`) character is inserted in the markup, instead, you are expected to insert it yourself if you need it in your app. + +## Filters + +Clients must do their own text filtering based on filters returned from the API. The server will apply `irreversible` filters for home and notifications context, but anything else is still up to the client to filter! + +Expired filters are not deleted by the server. They should no longer be applied but they are still stored by the server. It is up to clients to delete those filters eventually. diff --git a/content/fr/api/libraries.md b/content/fr/api/libraries.md new file mode 100644 index 00000000..aca2a99e --- /dev/null +++ b/content/fr/api/libraries.md @@ -0,0 +1,102 @@ +--- +title: Libraries +description: List of libraries that work with the Mastodon API in various programming languages +menu: + docs: + parent: api + weight: -1 +--- + +## Apex (Salesforce) + +- [apex-mastodon](https://github.com/tzmfreedom/apex-mastodon) + +## C# (.NET Standard) + +- [Mastodot](https://github.com/yamachu/Mastodot) +- [Mastonet](https://github.com/glacasa/Mastonet) +- [TootNet](https://github.com/cucmberium/TootNet) +- [mastodon-api-cs](https://github.com/pawotter/mastodon-api-cs) +- [Mastodon.Net](https://github.com/Tlaster/Mastodon.Net) + +## C++ + +- [mastodon-cpp](https://github.com/tastytea/mastodon-cpp) + +## Crystal + +- [mastodon.cr](https://github.com/decors/mastodon.cr) + +## Common Lisp + +- [tooter](https://github.com/Shinmera/tooter) + +## Elixir + +- [hunter](https://github.com/milmazz/hunter) + +## Go + +- [go-mastodon](https://github.com/mattn/go-mastodon) +- [madon](https://github.com/McKael/madon) + +## Haskell + +- [hastodon](https://github.com/syucream/hastodon) + +## Java + +- [mastodon4j](https://github.com/sys1yagi/mastodon4j) + +## JavaScript + +- [libodonjs](https://github.com/Zatnosk/libodonjs) + +## JavaScript (Browser) + +- [mastodon.js](https://github.com/Kirschn/mastodon.js) + +## JavaScript (Node.js) + +- [node-mastodon](https://github.com/jessicahayley/node-mastodon) +- [mastodon-api](https://github.com/vanita5/mastodon-api) + +## Perl + +- [Mastodon::Client](https://metacpan.org/pod/Mastodon::Client) + +## PHP + +- [Mastodon API for Laravel](https://github.com/kawax/laravel-mastodon-api) +- [Mastodon-api-php](https://github.com/yks118/Mastodon-api-php) +- [Composer based php API wrapper](https://github.com/r-daneelolivaw/mastodon-api-php) +- [MastodonOAuthPHP](https://github.com/TheCodingCompany/MastodonOAuthPHP) +- [Phediverse Mastodon REST Client](https://github.com/phediverse/mastodon-rest) +- [TootoPHP](https://framagit.org/MaxKoder/TootoPHP) +- [oauth2-mastodon](https://github.com/lrf141/oauth2-mastodon) +- [Mastodon Wordpress API](https://github.com/L1am0/mastodon_wordpress_api) + +## Python + +- [Mastodon.py](https://github.com/halcy/Mastodon.py) + +## R + +- [mastodon](https://github.com/ThomasChln/mastodon) + +## Ruby + +- [mastodon-api](https://github.com/tootsuite/mastodon-api) + +## Rust + +- [mammut](https://github.com/Aaronepower/mammut) +- [elefren](https://github.com/pwoolcoc/elefren) + +## Scala + +- [scaladon](https://github.com/schwitzerm/scaladon) + +## Swift + +- [MastodonKit](https://github.com/ornithocoder/MastodonKit) diff --git a/content/fr/api/parameters.md b/content/fr/api/parameters.md new file mode 100644 index 00000000..b1054e92 --- /dev/null +++ b/content/fr/api/parameters.md @@ -0,0 +1,44 @@ +--- +title: Parameters +description: Specifics of parameter passing to the Mastodon API +menu: + docs: + parent: api + weight: 3 +--- + +## Parameter format + +Query strings, form data, and JSON submitted via POST body is equally understood by the API. It is expected that query strings are used for GET requests, and form data or JSON is used for all other requests. + +## Arrays + +An array parameter must encoded using bracket notation, e.g. `array[0]=foo&array[1]=bar` would be translated into: + +```ruby +array = [ + 'foo', + 'bar', +] +``` + +## Booleans + +A boolean value is considered false for the values `0`, `f`, `F`, `false`, `FALSE`, `off`, `OFF`, considered to not be provided for empty strings, and considered to be true for all other values. + +## Files + +File uploads must be encoded using `multipart/form-data`. + +## Nested parameters + +Some parameters need to be nested. For that, bracket notation must also be used. For example, `source[privacy]=public&source[language]=en` would be translated into: + +```ruby +source = { + privacy: 'public', + language: 'en', +} +``` + +This can be combined with arrays as well. diff --git a/content/fr/api/permissions.md b/content/fr/api/permissions.md new file mode 100644 index 00000000..01770a07 --- /dev/null +++ b/content/fr/api/permissions.md @@ -0,0 +1,49 @@ +--- +title: Permissions +description: Overview of OAuth 2 access scopes in Mastodon +menu: + docs: + parent: api + weight: 2 +--- + +The API is divided up into access scopes: + +|Scope|Parent(s)|Added in| +|:----|---------|:------:| +|`write`||0.9.0| +|`write:accounts`|`write`|2.4.3| +|`write:blocks`|`write`, `follow`|2.4.3| +|`write:favourites`|`write`|2.4.3| +|`write:filters`|`write`|2.4.3| +|`write:follows`|`write`, `follow`|2.4.3| +|`write:lists`|`write`|2.4.3| +|`write:media`|`write`|2.4.3| +|`write:mutes`|`write`, `follow`|2.4.3| +|`write:notifications`|`write`|2.4.3| +|`write:reports`|`write`|2.4.3| +|`write:statuses`|`write`|2.4.3| +|`read`||0.9.0| +|`read:accounts`|`read`|2.4.3| +|`read:blocks`|`read`, `follow`|2.4.3| +|`read:favourites`|`read`|2.4.3| +|`read:filters`|`read`|2.4.3| +|`read:follows`|`read`, `follow`|2.4.3| +|`read:lists`|`read`|2.4.3| +|`read:mutes`|`read`, `follow`|2.4.3| +|`read:notifications`|`read`|2.4.3| +|`read:reports`|`read`|2.4.3| +|`read:search`|`read`|2.4.3| +|`read:statuses`|`read`|2.4.3| +|`follow`||0.9.0| +|`push`||2.4.0| + +The scopes are hierarchical, i.e. if you have access to `read`, you automatically have access to `read:accounts`. **It is recommended that you request as little as possible for your application.** + +Multiple scopes can be requested at the same time: During app creation with the `scopes` param, and during the authorization phase with the `scope` query param (space-separate the scopes). + +> **Note:** Mind the `scope` vs `scopes` difference. This is because `scope` is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon's own REST API uses the more appropriate `scopes`. + +If you do not specify a `scope` in your authorization request, or a `scopes` in your app creation request, the resulting access token / app will default to `read` access. + +The set of scopes saved during app creation must include all the scopes that you will request in the authorization request, otherwise authorization will fail. diff --git a/content/fr/api/push.md b/content/fr/api/push.md new file mode 100644 index 00000000..bc763643 --- /dev/null +++ b/content/fr/api/push.md @@ -0,0 +1,15 @@ +--- +title: Web Push API +overview: How to use the Web Push API in Mastodon to receive push notifications in a native or browser app +menu: + docs: + parent: api + weight: 5 +--- + +Mastodon natively supports the [Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). You can utilize the same mechanisms for your native app. It requires running a proxy server that connects to Android's and Apple's proprietary notification gateways. However, the proxy server does not have access to the contents of the notifications. For a reference, see [Mozilla's web push server](https://github.com/mozilla-services/autopush), or more practically, see: + +- [toot-relay](https://github.com/DagAgren/toot-relay) +- [PushToFCM](https://github.com/tateisu/PushToFCM) + +Using the Web Push API requires your app to have the `push` scope. To create a new Web Push API subscription, use [POST /api/v1/push/subscription]({{< relref "notifications.md#post-api-v1-push-subscription" >}}). diff --git a/content/fr/api/rest/accounts.md b/content/fr/api/rest/accounts.md new file mode 100644 index 00000000..9ff50292 --- /dev/null +++ b/content/fr/api/rest/accounts.md @@ -0,0 +1,203 @@ +--- +title: Accounts +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/accounts/:id + +Returns [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="No" user="No" scope="read read:accounts" version="0.0.0" >}} + +## POST /api/v1/accounts + +Returns [Token]({{< relref "entities.md#token" >}}) + +The method is available to apps with a token obtained via the client credentials grant. It creates a user and account records, as well as an access token for the app that initiated the request. The user is unconfirmed, and an e-mail is sent as usual. + +The method returns the access token, which the app should save for later. The REST API is not available to users with unconfirmed accounts, so the app must be smart to wait for the user to click a link in their e-mail inbox. + +The method is rate-limited by IP to 5 requests per 30 minutes. + +### Resource information + +{{< api_method_info auth="Yes" user="No" scope="write write:accounts" version="2.7.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `username` | User name | Required | +| `email` | E-mail address | Required | +| `password` | Password text | Required | +| `agreement` | Agreement to local rules, terms of use, privacy policy (Bool) | Required | +| `locale` | The language of the e-mail to be sent first | Required | + +The `agreement` parameter must be set to true after presenting the local rules, terms of use, privacy policy for the user and obtaining consent. + +## GET /api/v1/accounts/verify_credentials + +User's own account. + +Returns [Account]({{< relref "entities.md#account" >}}) with an extra [`source` attribute]({{< relref "entities.md#source" >}}). + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:accounts" version="0.0.0" >}} + +## PATCH /api/v1/accounts/update_credentials + +Update user's own account. + +Returns [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `display_name` | Display name | Optional | +| `note` | Biography | Optional | +| `avatar` | Avatar encoded using `multipart/form-data` | Optional | +| `header` | Header image encoded using `multipart/form-data` | Optional | +| `locked` | Enable follow requests | Optional | +| `source[privacy]` | Default post privacy preference | Optional | +| `source[sensitive]`| Whether to mark statuses as sensitive by default | Optional | +| `source[language]` | Override language on statuses by default (ISO6391) | Optional | +| `fields_attributes` | Profile metadata (max. 4) | Optional | + +## GET /api/v1/accounts/:id/followers + +Accounts which follow the given account. + +Returns array of [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="No" scope="read read:accounts" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `limit` | Maximum number of results | Optional | 40 | + +### Pagination + +{{< api_pagination >}} + +## GET /api/v1/accounts/:id/following + +Accounts which the given account is following. + +Returns array of [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="No" scope="read read:accounts" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `limit` | Maximum number of results | Optional | 40 | + +### Pagination + +{{< api_pagination >}} + +## GET /api/v1/accounts/:id/statuses + +An account's statuses. + +Returns array of [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="No" scope="read read:statuses" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default|Added in| +|----|-----------|:------:|:-----:|:------:| +| `only_media` | Only return statuses that have media attachments | Optional | false | | +| `pinned` | Only return statuses that have been pinned | Optional | false | | +| `exclude_replies` | Skip statuses that reply to other statuses | Optional | false | | +| `max_id` | Return results older than ID | Optional | | | +| `since_id` | Return results newer than ID | Optional | | | +| `min_id` | Return results immediately newer than ID | Optional | | | +| `limit` | Maximum number of results | Optional | 20 | | | +| `exclude_reblogs` | Skip statuses that are reblogs of other statuses | Optional | false | 2.7.0 | + +### Pagination + +{{< api_dynamic_pagination >}} + +## POST /api/v1/accounts/:id/follow + +Follow an account. + +Returns [Relationship]({{< relref "entities.md#relationship" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `reblogs` | Whether the followed account's reblogs will show up in the home timeline | Optional | true | + +## POST /api/v1/accounts/:id/unfollow + +Unfollow an account. + +Returns [Relationship]({{< relref "entities.md#relationship" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}} + +## GET /api/v1/accounts/relationships + +Relationship of the user to the given accounts in regards to following, blocking, muting, etc. + +Returns array of [Relationship]({{< relref "entities.md#relationship" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:follows" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `id` | Array of account IDs | Required | + +## GET /api/v1/accounts/search + +Search for matching accounts by username, domain and display name. + +Returns array of [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:accounts" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `q` | What to search for | Required || +| `limit` | Maximum number of results | Optional | 40 | +| `resolve` | Attempt WebFinger look-up | Optional | false | +| `following` | Only who the user is following | Optional | false | diff --git a/content/fr/api/rest/apps.md b/content/fr/api/rest/apps.md new file mode 100644 index 00000000..d35ea028 --- /dev/null +++ b/content/fr/api/rest/apps.md @@ -0,0 +1,38 @@ +--- +title: Apps +menu: + docs: + parent: rest-api + weight: 10 +--- + +## POST /api/v1/apps + +Create a new application to obtain OAuth2 credentials. + +Returns [App]({{< relref "entities.md#app" >}}) with `client_id` and `client_secret` + +### Resource information + +{{< api_method_info auth="No" user="No" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `client_name` | Name of your application | Required | +| `redirect_uris` | Where the user should be redirected after authorization | Required | +| `scopes` | Space separated list of [scopes]({{< relref "permissions.md" >}}) | Required | +| `website` | URL to the homepage of your app | Optional | + +> To display the authorization code to the end-user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in `redirect_uris` + +## GET /api/v1/apps/verify_credentials + +Confirm that the app's OAuth2 credentials work. + +Returns [App]({{< relref "entities.md#app" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="No" version="2.0.0" >}} diff --git a/content/fr/api/rest/blocks.md b/content/fr/api/rest/blocks.md new file mode 100644 index 00000000..bcc455e7 --- /dev/null +++ b/content/fr/api/rest/blocks.md @@ -0,0 +1,47 @@ +--- +title: Blocks +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/blocks + +Accounts the user has blocked. + +Returns array of [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read:blocks follow" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `limit` | Maximum number of results | Optional | 40 | + +### Pagination + +{{< api_pagination >}} + +## POST /api/v1/accounts/:id/block + +Block an account. + +Returns [Relationship]({{< relref "entities.md#relationship" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write:blocks follow" version="0.0.0" >}} + +## POST /api/v1/accounts/:id/unblock + +Unblock an account. + +Returns [Relationship]({{< relref "entities.md#relationship" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write:blocks follow" version="0.0.0" >}} diff --git a/content/fr/api/rest/custom-emojis.md b/content/fr/api/rest/custom-emojis.md new file mode 100644 index 00000000..00d412c1 --- /dev/null +++ b/content/fr/api/rest/custom-emojis.md @@ -0,0 +1,17 @@ +--- +title: Custom emoji +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/custom_emojis + +Custom emojis that are available on the server. + +Returns array of [Emoji]({{< relref "entities.md#emoji" >}}) + +### Resource information + +{{< api_method_info auth="No" user="No" version="2.0.0" >}} diff --git a/content/fr/api/rest/domain-blocks.md b/content/fr/api/rest/domain-blocks.md new file mode 100644 index 00000000..051dc6f8 --- /dev/null +++ b/content/fr/api/rest/domain-blocks.md @@ -0,0 +1,55 @@ +--- +title: Domain blocks +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/domain_blocks + +Domains the user has blocked. + +Returns array of string. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:blocks follow" version="1.4.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `limit` | Maximum number of results | Optional | 40 | + +### Pagination + +{{< api_pagination >}} + +## POST /api/v1/domain_blocks + +Block a domain to hide all public posts from it, all notifications from it, and remove all followers from it. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:blocks follow" version="1.4.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `domain` | Domain to block| Required | + +## DELETE /api/v1/domain_blocks + +Remove a domain block. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:blocks follow" version="1.4.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `domain` | Domain to unblock| Required | diff --git a/content/fr/api/rest/endorsements.md b/content/fr/api/rest/endorsements.md new file mode 100644 index 00000000..6f317e0b --- /dev/null +++ b/content/fr/api/rest/endorsements.md @@ -0,0 +1,41 @@ +--- +title: Endorsements +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/endorsements + +Accounts the user chose to endorse. + +Returns array of [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:account" version="2.5.0" >}} + +### Pagination + +{{< api_pagination >}} + +## POST /api/v1/accounts/:id/pin + +Endorse an account, i.e. choose to feature the account on the user's public profile. + +Returns [Relationship]({{< relref "entities.md#relationship" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="2.5.0" >}} + +## POST /api/v1/accounts/:id/unpin + +Undo endorse of an account. + +Returns [Relationship]({{< relref "entities.md#relationship" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="2.5.0" >}} diff --git a/content/fr/api/rest/favourites.md b/content/fr/api/rest/favourites.md new file mode 100644 index 00000000..fa4e15c2 --- /dev/null +++ b/content/fr/api/rest/favourites.md @@ -0,0 +1,43 @@ +--- +title: Favourites +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/favourites + +Statuses the user has favourited. + +Returns array of [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:favourites" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `limit` | Maximum number of results | Optional | 20 | + +### Pagination + +{{< api_pagination >}} + +## POST /api/v1/statuses/:id/favourite + +Favourite a status. + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:favourites" version="0.0.0" >}} + +## POST /api/v1/statuses/:id/unfavourite + +Undo the favourite of a status. + +Returns [Status]({{< relref "entities.md#status" >}}) diff --git a/content/fr/api/rest/filters.md b/content/fr/api/rest/filters.md new file mode 100644 index 00000000..93f53706 --- /dev/null +++ b/content/fr/api/rest/filters.md @@ -0,0 +1,75 @@ +--- +title: Filters +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/filters + +Text filters the user has configured that potentially must be applied client-side. + +Returns array of [Filter]({{< relref "entities.md#filter" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="2.4.3" >}} + +## POST /api/v1/filters + +Create a new filter. + +Returns [Filter]({{< relref "entities.md#filter" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="2.4.3" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `phrase` | Keyword or phrase to filter | Required | +| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required | +| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional | +| `whole_word` | Whether to consider word boundaries when matching | Optional | +| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Leave blank for no expiration | Optional | + +## GET /api/v1/filters/:id + +A text filter. + +Returns [Filter]({{< relref "entities.md#filter" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="2.4.3" >}} + +## PUT /api/v1/filters/:id + +Update a text filter. + +Returns [Filter]({{< relref "entities.md#filter" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="2.4.3" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `phrase` | Keyword or phrase to filter | Required | +| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required | +| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional | +| `whole_word` | Whether to consider word boundaries when matching | Optional | +| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Leave blank to not change | Optional | + +## DELETE /api/v1/filters/:id + +Delete a text filter. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="2.4.3" >}} diff --git a/content/fr/api/rest/follow-requests.md b/content/fr/api/rest/follow-requests.md new file mode 100644 index 00000000..161df7d1 --- /dev/null +++ b/content/fr/api/rest/follow-requests.md @@ -0,0 +1,43 @@ +--- +title: Follow requests +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/follow_requests + +Accounts that have requested to follow the user. + +Returns array of [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:follows follow" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `limit` | Maximum number of results | Optional | 40 | + +### Pagination + +{{< api_pagination >}} + +## POST /api/v1/follow_requests/:id/authorize + +Allow the account to follow the user. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}} + +## POST /api/v1/follow_requests/:id/reject + +Do not allow the account to follow the user. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write:follows follow" version="0.0.0" >}} diff --git a/content/fr/api/rest/follow-suggestions.md b/content/fr/api/rest/follow-suggestions.md new file mode 100644 index 00000000..31479526 --- /dev/null +++ b/content/fr/api/rest/follow-suggestions.md @@ -0,0 +1,25 @@ +--- +title: Follow suggestions +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/suggestions + +Accounts the user had past positive interactions with, but is not following yet. + +Returns array of [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read" version="2.4.3" >}} + +## DELETE /api/v1/suggestions/:account_id + +Remove account from suggestions. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read" version="2.4.3" >}} diff --git a/content/fr/api/rest/instances.md b/content/fr/api/rest/instances.md new file mode 100644 index 00000000..d8355481 --- /dev/null +++ b/content/fr/api/rest/instances.md @@ -0,0 +1,17 @@ +--- +title: Instances +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/instance + +Information about the server. + +Returns [Instance]({{< relref "entities.md#instance" >}}) + +### Resource information + +{{< api_method_info auth="No" user="No" version="0.0.0" >}} diff --git a/content/fr/api/rest/lists.md b/content/fr/api/rest/lists.md new file mode 100644 index 00000000..a4ffcce3 --- /dev/null +++ b/content/fr/api/rest/lists.md @@ -0,0 +1,127 @@ +--- +title: Lists +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/lists + +User's lists. + +Returns array of [List]({{< relref "entities.md#list" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}} + +## GET /api/v1/accounts/:id/lists + +User's lists that a given account is part of. + +Returns array of [List]({{< relref "entities.md#list" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}} + +## GET /api/v1/lists/:id/accounts + +Accounts that are in a given list. + +Returns array of [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `limit` | Maximum number of results | Optional | 40 | + +### Pagination + +>If you specify a `limit` of `0` in the query, all accounts will be returned without pagination. Otherwise, standard account pagination rules apply. + +{{< api_pagination >}} + +## GET /api/v1/lists/:id + +Returns [List]({{< relref "entities.md#list" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}} + +## POST /api/v1/lists + +Create a new list. + +Returns [List]({{< relref "entities.md#list" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `title` | The title of the list | Required | + +## PUT /api/v1/lists/:id + +Update a list. + +Returns [List]({{< relref "entities.md#list" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `title` | The title of the list | Required | + +## DELETE /api/v1/lists/:id + +Remove a list. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}} + +## POST /api/v1/lists/:id/accounts + +Add accounts to a list. + +> Only accounts already followed by the user can be added to a list. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `account_ids` | Array of account IDs | Required | + +## DELETE /api/v1/lists/:id/accounts + +Remove accounts from a list. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `account_ids` | Array of account IDs | Required | diff --git a/content/fr/api/rest/media.md b/content/fr/api/rest/media.md new file mode 100644 index 00000000..7c4a3c4e --- /dev/null +++ b/content/fr/api/rest/media.md @@ -0,0 +1,46 @@ +--- +title: Media attachments +menu: + docs: + parent: rest-api + weight: 10 +--- + +## POST /api/v1/media + +Upload a media attachment that can be used with a new status. + +Returns [Attachment]({{< relref "entities.md#attachment" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:media" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `file` | Media file encoded using `multipart/form-data` | Required | +| `description` | A plain-text description of the media for accessibility (max 420 chars) | Optional | +| `focus` | Two floating points, comma-delimited. See [focal points](#focal-points) | Optional | + +## PUT /api/v1/media/:id + +Update a media attachment. Can only be done before the media is attached to a status. + +Returns [Attachment]({{< relref "entities.md#attachment" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:media" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `description` | A plain-text description of the media for accessibility (max 420 chars) | Optional | +| `focus` | Two floating points, comma-delimited. See [focal points](#focal-points) | Optional | + +## Focal points + +Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. [See this for how to let users select focal point coordinates](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point). diff --git a/content/fr/api/rest/mutes.md b/content/fr/api/rest/mutes.md new file mode 100644 index 00000000..375c16af --- /dev/null +++ b/content/fr/api/rest/mutes.md @@ -0,0 +1,73 @@ +--- +title: Mutes +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/mutes + +Accounts the user has muted. + +Returns array of [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read:mutes follow" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `limit` | Maximum number of results | Optional | 40 | + +### Pagination + +{{< api_pagination >}} + +## POST /api/v1/accounts/:id/mute + +Mute an account. + +Returns [Relationship]({{< relref "entities.md#relationship" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write:mutes follow" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `notifications` | Whether the mute will mute notifications or not | Optional | true | + +## POST /api/v1/accounts/:id/unmute + +Unmute an account. + +Returns [Relationship]({{< relref "entities.md#relationship" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write:mutes follow" version="0.0.0" >}} + +## POST /api/v1/statuses/:id/mute + +Mute the conversation the status is part of, to no longer be notified about it. + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:mutes" version="1.4.2" >}} + +## POST /api/v1/statuses/:id/unmute + +Unmute the conversation the status is part of. + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:mutes" version="1.4.2" >}} diff --git a/content/fr/api/rest/notifications.md b/content/fr/api/rest/notifications.md new file mode 100644 index 00000000..bf9e6109 --- /dev/null +++ b/content/fr/api/rest/notifications.md @@ -0,0 +1,120 @@ +--- +title: Notifications +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/notifications + +Notifications concerning the user. + +Returns array of [Notification]({{< relref "entities.md#notification" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:notifications" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `max_id` | Return results older than ID | Optional || +| `since_id` | Return results newer than ID | Optional || +| `min_id` | Return results immediately newer than ID | Optional || +| `limit` | Maximum number of results | Optional | 20 | +| `exclude_types` | Array of types to exclude (e.g. `follow`, `favourite`, `reblog`, `mention`) | Optional || + +### Pagination + +{{< api_dynamic_pagination >}} + +## GET /api/v1/notifications/:id + +Returns [Notification]({{< relref "entities.md#notification" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:notifications" version="0.0.0" >}} + +## POST /api/v1/notifications/clear + +Delete all notifications from the server. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:notifications" version="0.0.0" >}} + +## POST /api/v1/notifications/dismiss + +Delete a single notification from the server. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:notifications" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `id` | Notification ID | Required | + +## POST /api/v1/push/subscription + +Add a Web Push API subscription to receive notifications. See also: [Web Push API]({{< relref "push.md" >}}) + +> Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted. + +Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `subscription[endpoint]` | Endpoint URL that called when notification is happen. | Required | +| `subscription[keys][p256dh]` | User agent public key. Base64 encoded string of public key of ECDH key using 'prime256v1' curve. | Required | +| `subscription[keys][auth]` | Auth secret. Base64 encoded string of 16 bytes of random data. | Required | +| `data[alerts][follow]` | Boolean of whether you want to receive follow notification event. | Optional | +| `data[alerts][favourite]` | Boolean of whether you want to receive favourite notification event. | Optional | +| `data[alerts][reblog]` | Boolean of whether you want to receive reblog notification event. | Optional | +| `data[alerts][mention]` | Boolean of whether you want to receive mention notification event. | Optional | + +## GET /api/v1/push/subscription + +Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}} + +## PUT /api/v1/push/subscription + +Update current Web Push API subscription. Only the `data` part can be updated, e.g. which types of notifications are desired. To change fundamentals, a new subscription must be created instead. + +Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `data[alerts][follow]` | Boolean of whether you want to receive follow notification event. | Optional | +| `data[alerts][favourite]` | Boolean of whether you want to receive favourite notification event. | Optional | +| `data[alerts][reblog]` | Boolean of whether you want to receive reblog notification event. | Optional | +| `data[alerts][mention]` | Boolean of whether you want to receive mention notification event. | Optional | + +## DELETE /api/v1/push/subscription + +Remove the current Web Push API subscription. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}} diff --git a/content/fr/api/rest/polls.md b/content/fr/api/rest/polls.md new file mode 100644 index 00000000..060cc363 --- /dev/null +++ b/content/fr/api/rest/polls.md @@ -0,0 +1,31 @@ +--- +title: Polls +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/polls/:id + +Returns [Poll]({{< relref "entities.md#poll" >}}) + +### Resource information + +{{< api_method_info auth="No" user="No" scope="read read:statuses" version="2.8.0" >}} + +## POST /api/v1/polls/:id/votes + +Vote on a poll. + +Returns [Poll]({{< relref "entities.md#poll" >}}) + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `choices` | Array of choice indices | Required | + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="2.8.0" >}} \ No newline at end of file diff --git a/content/fr/api/rest/reports.md b/content/fr/api/rest/reports.md new file mode 100644 index 00000000..5fc209fb --- /dev/null +++ b/content/fr/api/rest/reports.md @@ -0,0 +1,24 @@ +--- +title: Reports +menu: + docs: + parent: rest-api + weight: 10 +--- + +## POST /api/v1/reports + +Report an account. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:reports" version="1.1.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `account_id` | The ID of the account to report | Required | +| `status_ids` | The IDs of statuses to report as array | Optional | +| `comment` | Reason for the report (up to 1,000 characters) | Optional | +| `forward` | Whether to forward to the remote admin (in case of a remote account) | Optional | diff --git a/content/fr/api/rest/scheduled-statuses.md b/content/fr/api/rest/scheduled-statuses.md new file mode 100644 index 00000000..07bcfffa --- /dev/null +++ b/content/fr/api/rest/scheduled-statuses.md @@ -0,0 +1,51 @@ +--- +title: Scheduled Statuses +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/scheduled_statuses + +Get scheduled statuses. + +Returns array of [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="2.7.0" >}} + +## GET /api/v1/scheduled_statuses/:id + +Get scheduled status. + +Returns [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="2.7.0" >}} + +## PUT /api/v1/scheduled_statuses/:id + +Update Scheduled status. Only `scheduled_at` can be changed. To change the content, delete it and post a new status. + +Returns [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="2.7.0" >}} + +### Parameters + +|Name|Description|Required| +|----|-----------|:------:| +| `scheduled_at` | Timestamp string to schedule posting of status (ISO 8601) | Optional | + +## DELETE /api/v1/scheduled_statuses/:id + +Remove Scheduled status. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="2.7.0" >}} diff --git a/content/fr/api/rest/search.md b/content/fr/api/rest/search.md new file mode 100644 index 00000000..78d7720f --- /dev/null +++ b/content/fr/api/rest/search.md @@ -0,0 +1,24 @@ +--- +title: Search +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v2/search + +Search for content in accounts, statuses and hashtags. + +Returns [Results]({{< relref "entities.md#results" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:search" version="2.4.1" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `q` | The search query | Required || +| `resolve` | Attempt WebFinger look-up | Optional |false| diff --git a/content/fr/api/rest/statuses.md b/content/fr/api/rest/statuses.md new file mode 100644 index 00000000..d32a8a3b --- /dev/null +++ b/content/fr/api/rest/statuses.md @@ -0,0 +1,177 @@ +--- +title: Statuses +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/statuses/:id + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}} + +## GET /api/v1/statuses/:id/context + +What the status replies to, and replies to it. + +Returns [Context]({{< relref "entities.md#context" >}}) + +### Resource information + +{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}} + +## GET /api/v1/statuses/:id/card + +Link preview card for a status, if available. + +Returns [Card]({{< relref "entities.md#card" >}}) + +### Resource information + +{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}} + +## GET /api/v1/statuses/:id/reblogged_by + +Accounts that reblogged the status. + +Returns array of [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `limit` | Maximum number of results | Optional | 40 | + +### Pagination + +{{< api_pagination >}} + +## GET /api/v1/statuses/:id/favourited_by + +Accounts that favourited the status. + +Returns array of [Account]({{< relref "entities.md#account" >}}) + +### Resource information + +{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `limit` | Maximum number of results | Optional | 40 | + +### Pagination + +{{< api_pagination >}} + +## POST /api/v1/statuses + +Publish a new status. + +Returns [Status]({{< relref "entities.md#status" >}}) + +When `scheduled_at` option is present, +Returns [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Added in| +|----|-----------|:------:|:------:| +| `status` | The text of the status | Optional\* | +| `in_reply_to_id` | ID of the status you want to reply to | Optional | +| `media_ids` | Array of media IDs to attach to the status | Optional\* | +| `poll` | Nested parameters to attach a poll to the status | Optional\* |2.8.0| +| `sensitive` | Mark the media in the status as sensitive | Optional | +| `spoiler_text` | Text to be shown as a warning before the actual content | Optional | +| `visibility` | One of `direct`, `private`, `unlisted` `public` | Optional | +| `scheduled_at` | Timestamp string to schedule posting of status (ISO 8601) | Optional |2.7.0| +| `language` | Override language code of the toot (ISO 639-2) | Optional | + +> You must provide either `status` or `media_ids`, completely empty statuses are not allowed. Polls require a `status` and cannot be combined with `media_ids`. + +Poll parameters: + +|Name|Description|Required| +|----|-----------|:------:| +| `poll[options]` | Array of poll answer strings | Required | +| `poll[expires_in]` | Duration the poll should be open for in seconds | Required | +| `poll[multiple]` | Whether multiple choices should be allowed | Optional | +| `poll[hide_totals]` | Whether to hide totals until the poll ends | Optional | + +### Idempotency + +In order to prevent duplicate statuses, this endpoint accepts an `Idempotency-Key` header, which should be set to a unique string for each new status. In the event of a network error, a request can be retried with the same `Idempotency-Key`. Only one status will be created regardless of how many requests with the same `Idempotency-Key` did go through. + +See for more on idempotency and idempotency keys. + +### Scheduled status + +Allows users to schedule a toot (with media attachments) to be published at a certain future date. + +The scheduled date must be at least 5 minutes into the future. At most, 300 toots can be scheduled at the same time. Only 50 toots can be scheduled for any given day. + +When `scheduled_at` option is present, instead of creating a status, we only run status validation, and if it passes, we create an entry in scheduled_statuses which encodes the status attributes. Every 5 minutes, a scheduler iterates over the scheduled_statuses table to fetch the ones due in the next 5 minutes, and push them into a more precise Sidekiq queue. In Sidekiq, the individual statuses are created, with media attachments being unassigned from the scheduled status and assigned to the real one. + +This option was added since v2.7.0. + +## DELETE /api/v1/statuses/:id + +Remove a status. The status may still be available a short while after the call. + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}} + +## POST /api/v1/statuses/:id/reblog + +Reblog a status. + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}} + +## POST /api/v1/statuses/:id/unreblog + +Undo the reblog of a status. + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}} + +## POST /api/v1/statuses/:id/pin + +Pin user's own status to user's profile. + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="1.6.0" >}} + +## POST /api/v1/statuses/:id/unpin + +Remove pinned status from user's profile. + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="1.6.0" >}} diff --git a/content/fr/api/rest/timelines.md b/content/fr/api/rest/timelines.md new file mode 100644 index 00000000..54257953 --- /dev/null +++ b/content/fr/api/rest/timelines.md @@ -0,0 +1,123 @@ +--- +title: Timelines +menu: + docs: + parent: rest-api + weight: 10 +--- + +## GET /api/v1/timelines/home + +Statuses from accounts the user follows. + +Returns array of [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `max_id` | Return results older than ID | Optional || +| `since_id` | Return results newer than ID | Optional || +| `min_id` | Return results immediately newer than ID | Optional || +| `limit` | Maximum number of results | Optional | 20 | + + +## GET /api/v1/conversations + +Conversations for an account + +Returns array of [Conversation]({{< relref "entities.md#conversation" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="2.6.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `max_id` | Return results older than ID | Optional || +| `since_id` | Return results newer than ID | Optional || +| `min_id` | Return results immediately newer than ID | Optional || +| `limit` | Maximum number of results | Optional | 20 | + +### Pagination + +{{< api_dynamic_pagination >}} + +## GET /api/v1/timelines/public + +Public statuses known to the server. + +Returns array of [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `local` | Only local statuses | Optional |false| +| `only_media` | Only statuses with media attachments | Optional |false| +| `max_id` | Return results older than ID | Optional || +| `since_id` | Return results newer than ID | Optional || +| `min_id` | Return results immediately newer than ID | Optional || +| `limit` | Maximum number of results | Optional | 20 | + +### Pagination + +{{< api_dynamic_pagination >}} + +## GET /api/v1/timelines/tag/:hashtag + +Public statuses known to the server marked with a given hashtag. + +Returns array of [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `local` | Only local statuses | Optional |false| +| `only_media` | Only statuses with media attachments | Optional |false| +| `max_id` | Return results older than ID | Optional || +| `since_id` | Return results newer than ID | Optional || +| `min_id` | Return results immediately newer than ID | Optional || +| `limit` | Maximum number of results | Optional | 20 | + +### Pagination + +{{< api_dynamic_pagination >}} + +## GET /api/v1/timelines/list/:list_id + +Statuses from accounts on a given list. + +Returns array of [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="2.1.0" >}} + +### Parameters + +|Name|Description|Required|Default| +|----|-----------|:------:|:-----:| +| `max_id` | Return results older than ID | Optional || +| `since_id` | Return results newer than ID | Optional || +| `min_id` | Return results immediately newer than ID | Optional || +| `limit` | Maximum number of results | Optional | 20 | + +### Pagination + +{{< api_dynamic_pagination >}} diff --git a/content/fr/api/streaming.md b/content/fr/api/streaming.md new file mode 100644 index 00000000..8faaa3d2 --- /dev/null +++ b/content/fr/api/streaming.md @@ -0,0 +1,78 @@ +--- +title: Streaming API +description: How to use Mastodon's streaming API for live, real-time updates +menu: + docs: + parent: api + weight: 4 +--- + +Your application can use a [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) endpoint to receive updates in real-time. Server-sent events is an incredibly simple transport method that relies entirely on chunked-encoding transfer, i.e. the HTTP connection is kept open and receives new data periodically. + +Alternatively, a WebSocket connection can also be established. + +## Server-sent events (HTTP) +### Endpoints +#### GET /api/v1/streaming/user + +Returns events that are relevant to the authorized user, i.e. home timeline and notifications + +#### GET /api/v1/streaming/public + +Returns all public statuses + +#### GET /api/v1/streaming/public/local + +Returns all local statuses + +#### GET /api/v1/streaming/hashtag?tag=:hashtag + +Returns all public statuses for a particular hashtag + +#### GET /api/v1/streaming/hashtag/local?tag=:hashtag + +Returns all local statuses for a particular hashtag + +#### GET /api/v1/streaming/list?list=:list_id + +Returns statuses for a list + +#### GET /api/v1/streaming/direct + +Returns all direct messages + +### Stream contents + +The stream will contain events as well as heartbeat comments. Lines that begin with a colon (`:`) can be ignored by parsers, they are simply there to keep the connection open. Events have this structure: + +``` +event: name +data: payload +``` + +## WebSocket + +For WebSockets, there is only one URL path (`/api/v1/streaming`). The access token as well as the endpoint you are interested in must be provided with query params, respectively `access_token` and `stream`. Query params `list` and `tag` are likewise supported for relevant endpoints. + +Possible `stream` values: + +- `user` +- `public` +- `public:local` +- `hashtag` +- `hashtag:local` +- `list` +- `direct` + +## Event types + +|Event|Description|What's in the payload| +|-----|-----------|---------------------| +|`update`|A new status has appeared|[Status]({{< relref "entities.md#status" >}})| +|`notification`|A new notification has appeared|[Notification]({{< relref "entities.md#notification" >}})| +|`delete`|A status has been deleted|ID of the deleted status| +|`filters_changed`|Keyword filters have been changed|| + +The payload is JSON-encoded. + +> **Note:** In case of `filters_changed` event, `payload` is not defined. diff --git a/content/fr/development/activitypub.md b/content/fr/development/activitypub.md new file mode 100644 index 00000000..f7e17e51 --- /dev/null +++ b/content/fr/development/activitypub.md @@ -0,0 +1,136 @@ +--- +title: Conformité avec ActivityPub +description: Quels objets et propriétés de la spécification ActivityPub sont supportés par Mastodon +menu: + docs: + parent: development + weight: 5 +--- + +## Les API + +- Mastodon supporte la partie serveur-à-serveur de la [spécification ActivityPub](https://www.w3.org/TR/activitypub/). +- Il implémente la [spécification des signatures HTTP](https://tools.ietf.org/html/draft-cavage-http-signatures-10) pour l'authentification des messages reçus. +- Mastodon supporte aussi [les signatures de Données Liées (Linked Data Signatures)](https://w3c-dvcg.github.io/ld-signatures/) pour les payloads transférés. + +## Restrictions + +- Tous les identifiants d'objets doivent utiliser `https://` comme protocole. +- Les instances doivent fournir un point d'entrée [WebFinger](https://tools.ietf.org/html/rfc7033) pour transformer les noms d'utilisateur·ice·s en acteurs. +- Les activités attribuées à un acteur doivent avoir un identifiant sur le même hôte que l'acteur. + +## Activités + +|Activité supportée|Objets supportés| +|------------------|-----------------| +|`Accept`|`Follow`| +|`Add`|`Note`| +|`Announce`|`Object`| +|`Block`|`Object`| +|`Create`|`Note`, `Article`, `Image`, `Video`, `Page`| +|`Delete`|`Object`| +|`Flag`|`Object`| +|`Follow`|`Object`| +|`Like`|`Object`| +|`Move`|`Object`| +|`Reject`|`Follow`| +|`Remove`|`Note`| +|`Undo`|`Accept`, `Announce`, `Block`, `Follow`, `Like`| +|`Update`|`Object`| + +En ce qui concerne l'activité `Create`, seul l'objet `Note` est un objet de première classe dans Mastodon, puisque Mastodon est un service de microblogage. Pour les autres types d'objets supportés, Mastodon en crée une représentation sous la forme d'un pouet, par exemple, un `Article` ou `Page` devient un pouet avec le `name` et `url` de l'objet original, ce qui incitera les utilisateur·ice·s à aller sur l'URL originale pour lire l'article. Pour les objets `Image` et `Video`, le `name` est également utilisé pour remplir le contenu du pouet, avec le fichier original joint au pouet. + +L'activité `Flag` permet de signaler un contenu d'une autre instance, et son `object` peut être soit un ou plusieurs acteurs, soit un ou plusieurs objets attribués à plusieurs acteurs. Les activités `Add` et `Remove` ne fonctionnent qu'avec les [collections mises en avant](#featured-collection). L'activité `Delete` peut être utilisé pour supprimer toutes les données locales de l'expéditeur·ice quand l'`object` de l'activité est l'expéditeur·ice. L'activité `Update` n'est utilisée que pour mettre à jour le profil de l'expéditeur·ice. De la même manière, l'activité `Move` autorise la migration des abonné·e·s de l'expéditeur·ice (`object`) à un autre acteur (`target`), mais seulement si cet acteur référence l'expéditeur·ice dans la propriété `alsoKnownAs`. + +## Extensions +### Collection mise en avant + +Ce qui est connu dans Mastodon comme des "toots épinglés", ou des statuts qui sont toujours affichés en haut des profils, est implémenté en utilisant une propriété supplémentaire nommée `featured` et associée à l'acteur de l'objet, cette propriété pointe vers une `Collection` d'objets. Par exemple : + +```json +{ + "@context": [ + "https://www.w3.org/ns/activitystreams", + + { + "toot": "http://joinmastodon.org/ns#", + "featured": { + "@id": "toot:featured", + "@type": "@id" + } + } + ], + + "id": "https://exemple.fr/@alice", + "type": "Person", + "featured": "https://exemple.fr/@alice/collections/featured" +} +``` + +### Émojis personnalisés + +Mastodon supporte les émojis personnalisés, de petites images téléversées par les administrateur·ice·s et invocables par des codes courts (:Kappa: par exemple). Pour ça, un type `Emoji` est utilisé. Ces émojis personnalisés sont listés dans la propriété `tag` comme les objets `Mention` et `Hashtag`, puisque ce sont des entités qui affectent la manière dont sera rendue le texte. Par exemple : + +```json +{ + "@context": [ + "https://www.w3.org/ns/activitystreams", + + { + "toot": "http://joinmastodon.org/ns#", + "Emoji": "toot:Emoji" + } + ], + + "id": "https://exemple.fr/@alice/hello-world", + "type": "Note", + "content": "Hello world :Kappa:", + "tag": [ + { + "id": "https://exemple.fr/emoji/123", + "type": "Emoji", + "name": ":Kappa:", + "icon": { + "type": "Image", + "mediaType": "image/png", + "url": "https://exemple.fr/files/kappa.png" + } + } + ] +} +``` + +### Points de focale + +Mastodon supporte la définition d'un point de focale sur les images téléversées, pour que peu importe où l'image est affichée, le point de focale reste le même. Cette fonctionnalité est implémentée en utilisant une propriété supplémentaire nommée `focalPoint` sur les objets `Image`. La propriété consiste en un tableau de deux nombres flottants entre 0 et 1. Par exemple : + +```json +{ + "@context": [ + "https://www.w3.org/ns/activitystreams", + + { + "toot": "http://joinmastodon.org/ns#", + "focalPoint": { + "@container": "@list", + "@id": "toot:focalPoint" + } + } + ], + + "id": "https://exemple.fr/@alice/hello-world", + "type": "Note", + "content": "Une image est jointe à ce toot !", + "attachment": [ + { + "type": "Image", + "mediaType": "image/png", + "url": "https://exemple.fr/files/cats.png", + "focalPoint": [ + 0.55, + 0.43 + ] + } + ] +} +``` diff --git a/content/fr/development/overview.md b/content/fr/development/overview.md new file mode 100644 index 00000000..480ee65c --- /dev/null +++ b/content/fr/development/overview.md @@ -0,0 +1,118 @@ +--- +title: Vue d'ensemble +description: Comment mettre en place un environnement de développement pour Mastodon +menu: + docs: + parent: development + weight: 1 +--- + +Mastodon est une application **Ruby on Rails** avec un front-end **React.js**. Il suit les standards utilisées par ces frameworks, si vous êtes déjà familier·ère avec Rails ou React.js, vous n'aurez pas de mauvaises surprises. + +Le meilleur moyen de faire fonctionner Mastodon dans un environnement de développement est d'installer toutes les dépendances sur votre système, au lieu d'utiliser Docker ou Vagrant. Vous aurez besoin de Ruby, Node.js, PostgreSQL et Redis, ce qui est un set de dépendances relativement standard pour les applications Rails. + +## Environnements + +Un "environnement" est un set de valeurs de configuration destinés à un usage spécifique. Ces environnements sont : `development`, dans lequel vous modifiez du code ; `test`, dans lequel vous exécutez la suite automatisée de tests ; `staging`, qui permet de simuler en conditions quasi réelles ce qui serait utilisé par les utilisateur·ice·s ; et `production`, qui est destiné à être utilisé par le grand public. Mastodon fournit des configurations pour `development`, `test` et `production`. + +La valeur par défaut de la variable `RAILS_ENV` est `development`, vous n'avez donc rien à faire pour exécuter Mastodon en mode développement. En fait, la configuration de Mastodon a des valeurs par défaut adaptées pour l'environnement de développement, vous n'avez donc pas besoin d'un fichier `.env` sauf si vous voulez customiser certaines choses. Voici les différences entre un environnement de développement et un environnement de production : + +- Le code Ruby se recharge de lui-même quand vous le modifiez, ce qui signifie que vous n'avez pas besoin de redémarrer le serveur Rails pour voir vos changements +- Toutes les erreurs montrent les stack traces dans le navigateur, à la place d'une page d'erreur générique +- Webpack fonctionne sans interruption et recompile les ressources JS et CSS quand vous modifiez n'importe quel fichier front-end, et les pages se rechargent automatiquement +- La mise en cache est désactivée par défaut +- Un compte administrateur avec comme identifiant `admin@localhost:3000` et le mot de passe `mastodonadmin` est créé automatiquement durant l'exécution de la tâche `db:seed` + +Il est à noter que la configuration Docker fournie avec Mastodon est optimisée pour l'environnement de production, et que c'est donc très déconseillé pour une utilisation dans le but de faire du développement. La configuration Vagrant, en revanche, est faite spécialement pour le développement et non pour un usage en production. + +## Mise en place + +Après avoir cloné le projet et vous être placé dans le répertoire fraîchement créé, exécutez `bundle install` puis `yarn install`. + +Dans l'environnement de développement, Mastodon se connectera à PostgreSQL sous le nom de l'utilisateur Linux actuellement utilisé en employant la méthode `ident`, qui fonctionne directement dans la plupart des cas. La seule commande que vous avez à exécuter est `rails db:setup` qui va créer les bases de données `mastodon_development` et `mastodon_test`, charger le schéma associé, puis créer les données de bases pour `mastodon_development` qui sont définies dans le fichier `db/seed.rb`. Les seules données de bases sont le compte administrateur avec les identifiants `admin@localhost:3000` / `mastodonadmin`. + +> Gardez à l'esprit que par défaut, Mastodon sera accessible depuis le port 3000. Si vous choisissez un port différent, le compte administrateur généré utilisera ce nombre. + +## Exécution + +Il y a plusieurs processus qui doivent être démarrés pour profiter de toutes les fonctionnalités de Mastodon, mais on peut décider de ne pas en démarrer certains au cas par cas. Pour les démarrer tous en une seule commande, vous pouvez installer Foreman avec `gem install foreman --no-document` puis utiliser : + + foreman start + +dans le répertoire contenant Mastodon. Cela va démarrer les processus inscrits dans le fichier `Procfile.dev`, ce qui vous donnera : un serveur Rails, un serveur Webpack, l'API de streaming, et Sidekiq. Bien sûr, vous pouvez démarrer n'importe lequel de ces processus indépendamment en fonction de vos besoins. + +## Tests + +|Commande|Description| +|-------|-----------| +|`rspec`|Exécute la suite de tests Ruby| +|`yarn run test`|Exécute la suite de tests JavaScript| +|`rubocop`|Vérifie si le code Ruby est en conformité avec notre style de programmation| + +## Les bibliothèques logicielles les plus utilisées + +La connaissance et la compréhension de ces bibliothèques simplifiera le travail sur le code source de Mastodon. + +### Ruby + +- `haml`, un langage pour créer des templates +- `devise`, pour l'authentification +- `doorkeeper`, qui agit comme un fournisseur OAuth 2 +- `paperclip`, pour l'envoi de fichiers et de pièces jointes +- `sidekiq`, pour les tâches de fond + +### JavaScript + +- `immutable`, pour les structures de données immuables +- `react`, pour effectuer le rendu de l'application web dynamique +- `react-redux`, pour gérer l'état de React +- `react-router-dom`, pour la navigation dans React +- `react-intl`, pour les traductions dans React + +## Structure du code + +Ce qui suit n'a pas vocation à faire autorité ou à être exhaustif, mais plus à être une aide pour vous aider à vous retrouver dans l'application. + +### Ruby + +|Chemin |Description| +|----|-----------| +|`app/controllers`|Code qui relie les opérations aux templates| +|`app/helpers`|Code qui peut être récupéré depuis les vues, c-à-d les opérations banales| +|`app/lib`|Code qui ne rentre pas dans les autres catégories| +|`app/models`|Code qui représente des entités de données| +|`app/serializers`|Code qui génère du JSON à partir de modèles| +|`app/services`|Opérations complexes qui impliquent plusieurs modèles| +|`app/views`|Les templates pour générer des fichiers HTML ou autre| +|`app/workers`|Code qui s'exécute en dehors du cycle "requête-réponse"| +|`spec`|Les suites automatisées de tests| + +### JavaScript + +|Chemin|Description| +|----|-----------| +|`app/javascript/mastodon`|Code pour l'application React.js multi-colonnes | +|`app/javascript/packs`|Code pour les pages non-React.js| + +### CSS et autres ressources + +|Chemin|Description| +|----|-----------| +|`app/javascript/images`|Images| +|`app/javascript/styles`|Code qui se transforme en CSS via Sass| + +### Traductions + +|Chemin|Description| +|----|-----------| +|`config/locales`|Fichiers de traductions côté serveur au format YML| +|`app/javascript/mastodon/locales`|Fichiers de traductions côté client au format JSON| + +## Maintenance des traductions + +Tous les fichiers de traduction sont normalisés pour assurer un formatage et un ordre des valeurs constant, ce qui minimise les différences dans Git. + +|Commande|Description| +|-------|-----------| +|`i18n-tasks normalize`|Normalise les traductions côté serveur| +|`yarn run manage:translations`|Normalise les traductions côté client| diff --git a/content/fr/usage/basics.md b/content/fr/usage/basics.md new file mode 100644 index 00000000..2ed383d6 --- /dev/null +++ b/content/fr/usage/basics.md @@ -0,0 +1,68 @@ +--- +title: Les bases +description: Aperçu des fonctions de base de Mastodon +menu: + docs: + parent: usage + weight: 1 +--- +## Inscription + +Vous devez choisir une instance sur laquelle s'inscrire, comme vous choisiriez un fournisseur d'adresse e-mail ou un royaume pour votre personnage dans World of Warcraft. L'instance hébergera votre compte et votre timeline. + +Vous pouvez [parcourir une liste d'instance par catégorie et langue sur joinmastodon.org](https://joinmastodon.org/#getting-started). + +## Modifier son profil +### Image, nom et biographie + +- Vous pouvez téléverser une photo de profil +- Vous pouvez téléverser une bannière pour votre profil +- Vous pouvez définir un nom d'usage différent de votre nom d'utilisateur +- Vous pouvez vous présenter dans votre biographie +- Vous pouvez mentionner des gens et utiliser des hashtags ainsi que des émojis personnalisés dans votre biographie + +### Les méta-données du profil + +Les méta-données du profil sont un moyen d'ajouter des infos supplémentaires sur votre profil qui sera plus facile à lire. Vous disposez de 4 rangées dans lesquelles vous pouvez définir une étiquette et sa valeur. Par exemple : + +|Étiquette|Valeur| +|-----|-------| +|Âge|25| +|Pays|Allemagne| +|Pronoms|il/lui| + +C'est vous qui décidez de ce que vous mettez dedans. Les étiquettes et les valeurs peuvent contenir des @mentions, des #hashtags, des émojis personnalisés et des liens. + +### Vérification de lien + +Si vous mettez un lien dans les méta-données de votre profil, Mastodon vérifiera si le lien contient une indication renvoyant à votre profil Mastodon. Si c'est le cas, vous obtiendrez une coche à côté du lien, puisque vous avez prouvé que le lien vous appartient. + +En coulisses, Mastodon cherche l'attribut `rel="me"` dans la page. Mastodon met également `rel="me"` dans les liens affichés dans les méta-données de profil. + +## Envoyer un post +### Texte + +- Vous disposez de 500 caractères +- Vous pouvez mentionner d'autres personnes comme `@alice` ou `@alice@exemple.fr` +- Quand vous mentionnez d'autres personnes, la partie `exemple.fr` du nom d'utilisateur n'est pas affichée dans le message final +- Si vous postez des liens, ils doivent commencer par `http://` ou `https://` +- Quand vous postez un ou plusieurs lien(s), ils compteront tous pour 23 caractères, peu importe la longueur du lien +- Vous pouvez utiliser des hashtags comme `#exemple` pour que les autres puissent trouver votre post via ce tag +- Vous pouvez ajouter un avertissement de contenu à votre post +- L'avertissement de contenu est en texte basique. Il ne peut contenir de mentions, de hashtags ou de liens. + +### Médias + +- Vous pouvez téléverser des images au format PNG et JPG +- Les GIFs téléversés sont convertis en vidéos sans son au format MP4, comme sur Imgur/Gfycat (GIFV) +- Vous pouvez également téléverser directement des MP4 ou WebM sans son (GIFV) +- Vous pouvez téléverser des vidéos au format MP4, WebM ou MOV +- La taille limite des images téléversées est de 8 Mo +- La taille limite des vidéos téléversées est de 40 Mo +- Les images plus grandes que 1280x1280 pixels sont rétrécies +- Tous les médias d'un post peuvent être cachés derrière un spoiler + +### Émojis personnalisés + +- Chaque serveur offre un set d’émojis personnalisés à utiliser, comme sur Discord +- Vous pouvez utiliser un émoji en appelant son code, comme `:thounking:` diff --git a/content/fr/usage/decentralization.md b/content/fr/usage/decentralization.md new file mode 100644 index 00000000..45113410 --- /dev/null +++ b/content/fr/usage/decentralization.md @@ -0,0 +1,91 @@ +--- +title: Décentralisation +description: Comment Mastodon est décentralisé et ce que ça veut dire concrètement +menu: + docs: + parent: usage + weight: 2 +--- + +Mastodon est un réseau social **fédéré**. + +## Qu'est-ce que la fédération ? + +La **fédération** est une forme de décentralisation. Au lieu d'avoir un nœud de connexion unique que tout le monde utiliserait, il y en a plusieurs, que n'importe qui peut utiliser. + +|Degrés de centralisation|Exemples| +|:---------------------:|--------| +|Centralisé|Twitter, Facebook, Instagram| +|Fédéré|E-mail, XMPP| +|Distribué|BitTorrent, IPFS, Scuttlebutt| + +Une instance Mastodon peut opérer seule. Comme un site web traditionnel, les gens s'inscrivent dessus, postent des messages, envoient des photos et se parlent entre eux. *Contrairement* à un site web traditionnel, les instances Mastodon peuvent opérer entre elles, laissant leurs utilisateur·ice·s communiquer ensemble, comme vous enverriez un mail depuis votre adresse GMail à quelqu'un utilisant une adresse Outlook. + +

+ +

De gauche à droite : Centralisé, Fédéré, Distribué

+
+ +Concrètement : Imaginez si vous pouviez suivre quelqu'un sur Instagram depuis votre compte Twitter et commenter ses photos sans changer de compte ou d'application. Si Twitter et Instagram étaient des services fédérés, ce serait possible. + +## Le Fediverse + +Mastodon utilise un protocole ouvert et standardisé pour la fédération. Il se nomme ActivityPub. N'importe quel logiciel qui utilise également ActivityPub pour la fédération peut communiquer sans problèmes avec Mastodon, comme n'importe quelle instance Mastodon peut communiquer avec une autre. + +Le **Fediverse** ("federated universe", univers fédéré) est le nom qu'on donne à l'ensemble des instances qui peuvent communiquer entre elles. Ça inclut toutes les instances Mastodon, mais également d'autres logiciels : + +- Misskey +- Pleroma +- PeerTube +- Plume +- et plein d'autres encore + +Le Fediverse n'a pas de logiciel spécifique associé, vous entendrez donc plus souvent "suivez-moi sur Mastodon" que "suivez-moi sur le Fediverse", bien que le deuxième soit techniquement plus approprié. + +## Implications concrètes +### S'adresser à des gens + +Les noms d'utilisateur sur Mastodon sont en deux parties : + +- Le nom d'utilisateur local, ex. `alice` +- Et le nom de domaine de l'instance, ex. `exemple.fr` + +Comme une adresse e-mail. Par commodité, Mastodon vous permet de zapper la deuxième partie du nom d'utilisateur quand vous vous adressez à des gens sur la même instance que vous, mais rappelez-vous que si vous partagez votre nom d'utilisateur à d'autres personnes, vous devrez donner le nom complet ou sinon elles auront du mal à vous trouver. + +|{{< no >}}|{{< yes >}}| +|:--------:|:---------:| +|Je suis @alice sur Mastodon !|Je suis @alice@exemple.fr sur Mastodon !| + +La barre de recherche dans Mastodon peut trouver des gens soit sous la forme `@nom@domaine.tld`, soit sous la forme d'un lien (`https://exemple.fr/@nom`), vous pouvez donc partager sous la forme qui vous convient le mieux. + +### Suivre des gens + +Tant que vous rencontrez quelqu'un via l'interface utilisateur de l'application, ex. l'interface web de votre instance, ou votre application mobile, vous avez juste à cliquer sur le bouton "Suivre" et vous ne verrez aucune différence si la personne est sur votre instance ou non. + +Par contre, si vous arrivez sur la page publique d'une personne sur une autre instance, il y a un problème : l'instance vous voit comme un·e simple inconnu·e. + +Quand vous cliquez sur "Suivre", une fenêtre va apparaître, vous demandant d'entrer votre nom d'utilisateur complet (avec la partie du nom de domaine, la plus importante). Ainsi, la fenêtre vous renverra sur votre instance et vous permettra de suivre la personne. + +Vous verrez aussi cette fenêtre quand vous cliquez sur "Répondre", "Boost" ou "Mettre en favori" sur les pages publiques d'autres instances. + +### Parcourir le contenu + +Afin de vous permettre de découvrir du contenu potentiellement intéressant, Mastodon fournit un moyen de parcourir tous les posts publics. Enfin, il n'y pas pas d'accord global de partage du contenu entre toutes les instances, donc il n'y a pas vraiment de moyen de parcourir *tous* les posts publics. Quand vous parcourez la **timeline fédérée**, vous voyez tous les posts publics que l'instance sur laquelle vous êtes connaît. Il y a différentes façons de faire découvrir à votre instance des posts, mais la manière la plus simple est de suivre des gens d'autres instances. + +Il y a un moyen de filtrer la timeline fédérée afin de ne voir que les posts publics faits à partir de votre instance : la **timeline locale**. Note que "locale" se réfère à l'instance, pas à une position géographique. + +### Financement et monétisation + +Toutes les instances Mastodon sont gérées par des personnes ou des organisations complètement différentes et indépendantes. Mastodon n'offre aucune solution de monétisation dans le logiciel. + +Quelques administrateur·ice·s d'instances choisissent de fournir des comptes contre de l'argent. D'autres travaillent dans des entreprises ou des organismes du service public qui utilisent leur infrastructure déjà existante pour héberger leur instance. La plupart des administrateur·ice·s d'instances s'en réfèrent au crowdfunding via Patreon ou autre pour payer les frais de service. Si vous voulez soutenir l'instance qui héberge votre compte, cherchez s'il est fait mention d'un moyen de financer l'instance. + +Le développement de Mastodon est financé par crowdfunding via Patreon. Aucun capital-risque n'est impliqué. + +### Usurpation d'identité et vérification + +Le même nom d'utilisateur *peut* être utilisé sur différentes instances, il n'y a aucun moyen de réclamer la propriété de chaque nom à l'avance. Comme avec les mails, vous ne devriez pas vous attendre à ce que `alice@hotmail.com` soit la même Alice que `alice@gmail.com`. + +Puisque Mastodon peut être auto-hébergé, il n'y a de meilleur moyen de prouver son identité qu'en ayant une instance sur un nom de domaine vous appartenant, les gens y faisant déjà confiance. + +La vérification d'identité via des documents et l'apposition d'une coche bleue à côté de son nom ne sont pas possible sans une autorité centralisée. Par contre, Mastodon peut croiser les liens que vous mettez sur votre profil pour prouver que vous détenez la propriété de ces liens. Si l'un de ces liens est votre page web personnelle qui est connue et donc de confiance, cela peut servir comme une alternative à la vérification d'identité. diff --git a/content/fr/usage/moderation.md b/content/fr/usage/moderation.md new file mode 100644 index 00000000..79c93c01 --- /dev/null +++ b/content/fr/usage/moderation.md @@ -0,0 +1,73 @@ +--- +title: Modération +description: Aperçu des outils de modération de Mastodon +menu: + docs: + parent: usage + weight: 4 +--- +## Modération individuelle + +La modération dans Mastodon se fait toujours localement, c-à-d que les actions ne se verront que depuis l'instance où elles ont été prises. Un·e administrateur·ice ou modérateur·ice d'une instance ne peut s'en prendre à une personne d'une autre instance, ses actions n'ont de conséquences que sur la copie locale sur leur propre instance. + +### Désactiver la connexion + +Un compte Mastodon peut être désactivé. Cela empêche l'utilisateur·ice de faire quoi que ce soit avec son compte, mais tout ce qui a été posté reste là. Cette restriction est réversible, le compte peut être réactivé à tout moment. Cette restriction n'est disponible que pour les utilisateur·ice·s de votre instance. + +### Silence + +Un silence (masquage) sur Mastodon est comparable au sandbox en informatique. Un compte silencé n'apparaît pas aux personnes qui ne le suivaient pas auparavant. Le contenu est toujours là, et il peut toujours être trouvé en le cherchant, quand on clique sur la @mention ou quand on cherche dans sa propre liste d'abonnements, mais il est invisible pour les autres. + +À ce stade, le silence n'affecte pas la fédération. Un compte localement silencé n'est *pas* silencé automatiquement sur les autres instances. + +Cette restriction est réversible, le compte peut être dé-silencé à tout moment. + +### Suspension + +Une suspension sur Mastodon est synonyme de suppression. Le compte n'apparaît plus quand on le cherche, la page de profil disparaît, tous les posts, téléversements, liste d'abonnements et d'abonné·e·s, et toutes les autres données sont supprimées. Cette restriction est **irréversible**. Bien que le compte puisse être dé-suspendu, permettant ainsi à l'utilisateur·ice d'en regagner l'accès, les anciennes données sont définitivement effacées. + +## Modération globale d'une instance + +La modération individuelle d'un grand nombre de personnes d'une instance ayant une mauvaise attitude pouvant être épuisant, il est possible de modérer préventivement tous les utilisateur·ice·s de cette instance en utilisant un **blocage de domaine**, qui se décline en plusieurs degrés de sévérité. + +### Rejet des médias + +Quand cette option est activée, aucun fichier de cette instance sera accepté localement. Cela comprend les photos de profil, les bannières, les émojis personnalisés et les médias rattachés aux posts. + +### Masquage + +Applique un masquage sur tous les comptes passés et futurs de cette instance. + +### Suspendre + +Applique une suspension à tous les comptes passés et futurs de cette instance. Aucun contenu de cette instance sera stocké localement, à part les noms d'utilisateur. + +## Mesures anti-spam + +Il y a quelques mesures de base qui limitent le spam sur Mastodon : + +- L'inscription requiert la confirmation de son adresse mail +- Le nombre d'inscriptions via la même adresse IP est limité + +Toutefois, les spammeurs et spammeuses déterminé·e·s arriveront à passer outre ces mesures. Vous pouvez alors user du **blacklisting de domaines courriel**. Durant l'inscription, Mastodon cherche un enregistrement A ou MX dans le nom de domaine utilisé par l'adresse mail, c-à-d l'adresse IP du serveur mail, et vérifie si cette adresse n'est pas dans une blacklist générée dynamiquement. + +### Blocage de serveur de courriel + +Les spammeur·euse·s vont souvent utiliser plusieurs domaines de courriel pour que ça donne l'impression qu'iels utilisent plein de serveurs différents et qu'il serait donc plus difficile de tous les bloquer. Cependant, l'expérience montre que la plupart du temps tous ces domaines renvoient à la même adresse IP. Si vous voyez plein de spammeur·euse·s s'inscrire en même temps, vous pouvez vérifier si c'est le cas ici, soit en utilisant un service de recherche DNS en ligne, ou en utilisant l'utilitaire `dig` sur Linux, par exemple `dig 1.2.3.4` retournera tous les enregistrements DNS pour cette adresse IP. Si l'IP est la même pour tous les domaines mail, vous pouvez l'ajouter dans la blacklist de domaines de courriels. + +### Blocage d'adresse IP + +Il n'est pas possible de bloquer les visiteurs sur la base de leur adresse IP dans Mastodon en soi, et ce n'est pas une stratégie infaillible. Les adresses IP sont parfois partagées par différentes personnes (entreprise, école…) et peuvent parfois changer de propriétaire. Mais il est possible de bloquer des visiteurs sur la base de leur adresse IP dans Linux en utilisant un pare-feu. Voici un exemple avec `iptables` et `ipset` : + +```bash +# Installez ipset +sudo apt install ipset +# Créez une blacklist nommée "spambots" +sudo ipset create spambots nethash +# Ajoutez 1.2.3.4 à la blacklist +sudo ipset add spambots 1.2.3.4 +# Ajoutez une règle de pare-feu basée sur la blacklist +sudo iptables -I INPUT 1 -m set --match-set spambots src -j DROP +``` + +Prenez garde à ne pas vous interdire de connexion à votre serveur. diff --git a/content/fr/usage/privacy.md b/content/fr/usage/privacy.md new file mode 100644 index 00000000..b7141d6a --- /dev/null +++ b/content/fr/usage/privacy.md @@ -0,0 +1,75 @@ +--- +title: Vie privée +description: Aperçu des fonctionnalités de Mastodon en rapport à la vie privée et leurs implications +menu: + docs: + parent: usage + weight: 3 +--- + +## Niveaux de publication + +|Niveau|Timelines publiques|Permalien|Page de profil public|Timeline personnelle| +|-----|:--------------:|:-------:|:----------:|:--------:| +|Public|{{< yes >}}|{{< yes >}}|{{< yes >}}|{{< yes >}}| +|Non-listé|{{< no >}}|{{< yes >}}|{{< yes >}}|{{< yes >}}| +|Abonné·e·s seulement|{{< no >}}|{{< no >}}|{{< no >}}|{{< yes >}}| +|Direct|{{< no >}}|{{< no >}}|{{< no >}}|{{< no >}}| + +Peu importe le niveau utilisé, chaque utilisateur·ice mentionné·e pourra voir le message dans ses notifications. + +**Ne partagez pas d'informations sensibles ou dangereuses par messages directs**. Mastodon n'est pas une messagerie instantanée chiffrée comme Signal ou Wire, les administrateur·ice·s des instances de l'expéditeur et du destinataire ont accès à la base de données de leurs instances et peuvent donc lire les messages. Utilisez donc les messages privés avec autant d'attention que vous feriez avec les DM Twitter, MP Discord et autres. + +## Verrouiller un compte + +Pour s'assurer que les posts privés (abonné·e·s seulement) le restent, vous devez verrouiller votre compte --sinon, n'importe qui pourrait vous suivre et voir vos posts précédents. Verrouiller son compte sur Mastodon ne fait qu'une chose : ajouter une étape de validation avant de pouvoir vous suivre. + +Une fois verrouillé, avant que quelqu'un puisse devenir votre abonné·e, vous recevrez une demande de suivi, que vous pouvez soit accepter soit refuser. + +Gardez à l'esprit que la possibilité de rendre privés ses posts se fait au cas par cas et non sur tout le compte, il n'y a donc aucun moyen de rendre instantanément les posts antérieurs privés. + +## Bloquer et masquer +### Masquer les boosts + +Si vous masquez les boosts de quelqu'un, vous ne les verrez pas dans votre timeline personnelle. + +### Masquer quelqu'un + +Quand vous masquez quelqu'un, vous avez la possibilité de masquer ou non les notifications venant de cette personne. Masquer quelqu'un sans pour autant masquer les notifications enlève de votre vue l'utilisateur·ice : + +- Vous ne verrez pas la personne dans votre timeline personnelle +- Vous ne verrez pas les autres partager ses posts +- Vous ne verrez pas les autres mentionner cette personne +- Vous ne verrez pas la personne dans les timelines publiques + +Si vous choisissez également de masquer les notifications de cette personne, vous ne recevrez pas de notifications de cette personne. + +La personne masquée ne sait à aucun moment qu'elle est masquée. + +### Bloquer quelqu'un + +Le blocage enlève de votre vue une personne : + +- Vous ne verrez pas la personne dans votre timeline personnelle +- Vous ne verrez pas les autres partager ses posts +- Vous ne verrez pas les autres mentionner cette personne +- Vous ne verrez pas la personne dans les timelines publiques +- Vous ne verrez pas les notifications de cette personne + +De plus, du côté de la personne bloquée : + +- Elle est obligée de ne plus vous suivre +- Elle ne peut pas vous suivre +- Elle ne verra pas les autres partager vos messages +- Elle ne vous verra plus dans les timelines publiques + +Si vous et la personne bloquée êtes sur la même instance, elle ne pourra plus voir vos posts en regardant votre profil tout en étant connecté. + +### Masquer toute une instance + +Si vous masquez une instance entière : + +- Vous ne verrez pas les posts de cette instance sur les timelines publiques +- Vous ne verrez pas les autres partager les posts de cette instance dans votre timeline personnelle +- Vous ne verrez pas les notifications de cette instance +- Vous perdrez les abonné·e·s que vous aviez potentiellement sur cette instance