From a99e71ce24f8a927563e6641124faee17edd39ff Mon Sep 17 00:00:00 2001 From: Felix Ableitner Date: Tue, 20 Apr 2021 17:58:56 +0200 Subject: [PATCH] Delete untranslated files --- src/fr/client_development/api_reference.md | 49 -------- .../client_development/client_development.md | 6 - src/fr/client_development/custom_frontend.md | 66 ---------- src/fr/client_development/http_api.md | 116 ------------------ src/fr/client_development/theming.md | 19 --- src/fr/contributing/contributing.md | 40 ------ src/fr/contributing/docker_development.md | 32 ----- src/fr/contributing/federation_development.md | 69 ----------- src/fr/contributing/local_development.md | 85 ------------- src/fr/contributing/tests.md | 29 ----- 10 files changed, 511 deletions(-) delete mode 100644 src/fr/client_development/api_reference.md delete mode 100644 src/fr/client_development/client_development.md delete mode 100644 src/fr/client_development/custom_frontend.md delete mode 100644 src/fr/client_development/http_api.md delete mode 100644 src/fr/client_development/theming.md delete mode 100644 src/fr/contributing/contributing.md delete mode 100644 src/fr/contributing/docker_development.md delete mode 100644 src/fr/contributing/federation_development.md delete mode 100644 src/fr/contributing/local_development.md delete mode 100644 src/fr/contributing/tests.md diff --git a/src/fr/client_development/api_reference.md b/src/fr/client_development/api_reference.md deleted file mode 100644 index f6436c0..0000000 --- a/src/fr/client_development/api_reference.md +++ /dev/null @@ -1,49 +0,0 @@ -# API reference - -Lemmy has two, intertwined APIs: -- [WebSocket](https://join.lemmy.ml/api/index.html) -- [HTTP](http_api.md) - -This page describes concepts that are common to both. - - - -- [Basic usage](#basic-usage) -- [Data types](#data-types) - * [Lemmy types](#lemmy-types) - * [Lower-level types](#lower-level-types) -- [Default rate limits](#default-rate-limits) - - - -## Basic usage - -Request and response strings are in [JSON format](https://www.json.org). - -## Data types - -### Lemmy types - -- [Source tables, that have the columns / fields](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/interfaces/source.ts) -- [Aggregates (for things like scores)](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/interfaces/aggregates.ts) -- [Views - The main lemmy return types](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/interfaces/views.ts) -- [Request Forms / Responses are in this folder](https://github.com/LemmyNet/lemmy-js-client/tree/main/src/interfaces/api) - -### Lower-level types - -- `?` designates an option which may be omitted in requests and not be present in responses. It will be of type ***SomeType***. -- `[SomeType]` is a list which contains objects of type ***SomeType***. -- Times and dates are timestamp strings in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC, your client must do the UTC to local conversion. - -## Default rate limits - -These can be edited in your `lemmy.hjson` file, by copying the relevant section from [defaults.hjson](https://github.com/LemmyNet/lemmy/blob/main/config/defaults.hjson). - -- 3 per hour for signups and community creation. -- 6 per hour for image posting. -- 6 per 10 minutes for post creation. -- 180 actions per minute for post voting and comment creation. - -Everything else is not rate-limited. - -**See also:** [rate limiting for custom front-ends](custom_frontend.md#rate-limiting). diff --git a/src/fr/client_development/client_development.md b/src/fr/client_development/client_development.md deleted file mode 100644 index a5e6fef..0000000 --- a/src/fr/client_development/client_development.md +++ /dev/null @@ -1,6 +0,0 @@ -# Client Development - -- [Theming Guide](client_development/theming.md) -- [API reference](client_development/api_reference.md) -- [WebSocket API](https://join.lemmy.ml/api/index.html) -- [HTTP API](client_development/http_api.md) \ No newline at end of file diff --git a/src/fr/client_development/custom_frontend.md b/src/fr/client_development/custom_frontend.md deleted file mode 100644 index 62c8fda..0000000 --- a/src/fr/client_development/custom_frontend.md +++ /dev/null @@ -1,66 +0,0 @@ -# Creating a Custom Frontend - -The backend and frontend are completely decoupled, and run in independent Docker containers. They only communicate over the [Lemmy API](api_reference.md), which makes it quite easy to write alternative frontends. - -This creates a lot of potential for custom frontends, which could change much of the design and user experience of Lemmy. For example, it would be possible to create a frontend in the style of a traditional forum like [phpBB](https://www.phpbb.com/), or a question-and-answer site like [stackoverflow](https://stackoverflow.com/). All without having to think about database queries, authentification or ActivityPub, which you essentially get for free. - -## Development - -You can use any language to create a custom frontend. The easiest option would be forking our [official frontend](https://github.com/LemmyNet/lemmy-ui), [lemmy-lite](https://github.com/IronOxidizer/lemmy-lite), or the [lemmy-frontend-example](https://github.com/LemmyNet/lemmy-front-end-example). In any case, the principle is the same: bind to `LEMMY_EXTERNAL_HOST` (default: `localhost:8536`) and handle requests using the Lemmy API at `LEMMY_INTERNAL_HOST` (default: `lemmy:8536`). Also use `LEMMY_HTTPS` to generate links with the correct protocol. - -The next step is building a Docker image from your frontend. If you forked an existing project, it should already include a `Dockerfile` and instructions to build it. Otherwise, try searching for your language on [dockerhub](https://hub.docker.com/), official images usually have build instructions in their readme. Build a Docker image with a tag, then look for the following section in `docker/dev/docker-compose.yml`: - -``` - lemmy-ui: - image: dessalines/lemmy-ui:v0.8.10 - ports: - - "1235:1234" - restart: always - environment: - - LEMMY_INTERNAL_HOST=lemmy:8536 - - LEMMY_EXTERNAL_HOST=localhost:8536 - - LEMMY_HTTPS=false - depends_on: - - lemmy -``` - -All you need to do is replace the value for `image` with the tag of your own Docker image (and possibly the environment variables if you need different ones). Then run `./docker_update.sh`, and after compilation, your frontend will be available on `http://localhost:1235`. You can also make the same change to `docker/federation/docker-compose.yml` and run `./start-local-instances.bash` to test federation with your frontend. - -## Deploy with Docker - -After building the Docker image, you need to push it to a Docker registry (such as [dockerhub](https://hub.docker.com/)). Then update the `docker-compose.yml` on your server, replacing the `image` for `lemmy-ui`, just as described above. Run `docker-compose.yml`, and after a short wait, your instance will use the new frontend. - -Note, if your instance is deployed with Ansible, it will override `docker-compose.yml` with every run, reverting back to the default frontend. In that case you should copy the `ansible/` folder from this project to your own repository, and adjust `docker-compose.yml` directly in the repo. - -It is also possible to use multiple frontends for the same Lemmy instance, either using subdomains or subfolders. To do that, don't edit the `lemmy-ui` section in `docker-compose.yml`, but duplicate it, adjusting the name, image and port so they are distinct for each. Then edit your nginx config to pass requests to the appropriate frontend, depending on the subdomain or path. - -## Translations - -You can add the [lemmy-translations](https://github.com/LemmyNet/lemmy-translations) repository to your project as a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). That way you can take advantage of same translations used in the official frontend, and you will also receive new translations contributed via weblate. - -## Rate limiting - -Lemmy does rate limiting for many actions based on the client IP. But if you make any API calls on the server side (eg in the case of server-side rendering, or javascript pre-rendering), Lemmy will take the IP of the Docker container. Meaning that all requests come from the same IP, and get rate limited much earlier. To avoid this problem, you need to pass the headers `X-REAL-IP` and `X-FORWARDED-FOR` on to Lemmy (the headers are set by our nginx config). - -Here is an example snipped for NodeJS: - -```javascript -function setForwardedHeaders( - headers: IncomingHttpHeaders -): { [key: string]: string } { - let out = { - host: headers.host, - }; - if (headers['x-real-ip']) { - out['x-real-ip'] = headers['x-real-ip']; - } - if (headers['x-forwarded-for']) { - out['x-forwarded-for'] = headers['x-forwarded-for']; - } - - return out; -} - -let headers = setForwardedHeaders(req.headers); -let client = new LemmyHttp(httpUri, headers); -``` \ No newline at end of file diff --git a/src/fr/client_development/http_api.md b/src/fr/client_development/http_api.md deleted file mode 100644 index f75e7e6..0000000 --- a/src/fr/client_development/http_api.md +++ /dev/null @@ -1,116 +0,0 @@ -# Lemmy HTTP API - - - - -- [Websocket vs HTTP API](#websocket-vs-http-api) -- [Examples](#examples) - * [TypeScript](#typescript) - * [Curl](#curl) - + [GET](#get-example) - + [POST](#post-example) -- [HTTP API exclusive features](#http-api-exclusive-features) - * [RSS/Atom feeds](#rss-atom-feeds) - * [Images](#images) - + [Create (request)](#create-request) - + [Create (response)](#create-response) - * [Delete](#delete) - - - -## WebSocket vs HTTP API -Lemmy's HTTP API is almost identical to its WebSocket API: -- **WebSocket API** needs `let send = { op: userOperation[op], data: form}` as shown in [the WebSocketAPI specification](https://join.lemmy.ml/api/index.html) -- **HTTP API** needs the form (data) at the top level, an HTTP operation (GET, PUT or POST) and endpoint (at `http(s)://host/api/v2/endpoint`). For example: - -> `POST {username_or_email: X, password: X}` - -For more information, see the [http.ts](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/http.ts) file. - -[The WebSocket API](https://join.lemmy.ml/api/index.html) should be regarded as the primary source for the HTTP API since it also provides information about how to form HTTP API calls. - -## Examples - -### TypeScript - -```ts - async editComment(form: EditComment): Promise { - return this.wrapper(HttpType.Put, '/comment', form); - } -``` - -| Type | URL | Body type | Return type | -| --- | --- | --- | --- | -| `PUT` | `/comment` | `EditComment` | `CommentResponse` | - -### Curl - -**GET example** - -``` -curl "http://localhost:8536/api/v2/community/list?sort=Hot"` -``` - -**POST example** - -``` -curl -i -H \ -"Content-Type: application/json" \ --X POST \ --d '{ - "comment_id": 374, - "score": 1, - "auth": eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MiwiaXNzIjoidGVzdC5sZW1teS5tbCJ9.P77RX_kpz1a_geY5eCp29sl_5mAm-k27Cwnk8JcIZJk -}' \ -http://localhost:8536/api/v2/comment/like -``` - -## HTTP API exclusive features - -These features cannot be accessed from the WebSocket API: - -- [RSS/Atom feeds](#rss-atom-feeds) -- [Images](#images) - -### RSS/Atom feeds - -- All - `/feeds/all.xml?sort=Hot` -- Community - `/feeds/c/community-name.xml?sort=Hot` -- User - `/feeds/u/user-name.xml?sort=Hot` - -### Images - -Lemmy forwards image requests to a locally running Pictrs. - -`GET /pictrs/image/{filename}?format={webp, jpg, ...}&thumbnail={96}` - -*Format and thumbnail are optional.* - -#### Create (request) - -Uploaded content must be valid multipart/form-data with an image array located within the images[] key. - -`POST /pictrs/image` - -#### Create (response) - -``` -{ - "files": [ - { - "delete_token": "{token}", - "file": "{file}.jpg" - } - ], - "msg": "ok" -} -``` - -#### Delete - -`GET /pictrs/image/delete/{delete_token}/{file}` - - -# Note - -This documentation may lag behind the actual [API endpoints](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/http.ts) and the API itself should be considered unstable (since it may change at any time). diff --git a/src/fr/client_development/theming.md b/src/fr/client_development/theming.md deleted file mode 100644 index 2610b5f..0000000 --- a/src/fr/client_development/theming.md +++ /dev/null @@ -1,19 +0,0 @@ -# Theming Guide - -Lemmy uses [Bootstrap v4](https://getbootstrap.com/), and very few custom css classes, so any bootstrap v4 compatible theme should work fine. - -## Creating - -- Use a tool like [bootstrap.build](https://bootstrap.build/) to create a bootstrap v4 theme. Export the `bootstrap.min.css` once you're done, and save the `_variables.scss` too. - -## Testing - -- To test out a theme, you can either use your browser's web tools, or a plugin like stylus to copy-paste a theme, when viewing Lemmy. - -## Adding - -1. Fork the [lemmy-ui](https://github.com/LemmyNet/lemmy-ui). -1. Copy `{my-theme-name}.min.css` to `src/assets/css/themes`. (You can also copy the `_variables.scss` here if you want). -1. Go to `src/shared/utils.ts` and add `{my-theme-name}` to the themes list. -1. Test locally -1. Do a pull request with those changes. diff --git a/src/fr/contributing/contributing.md b/src/fr/contributing/contributing.md deleted file mode 100644 index 92a363e..0000000 --- a/src/fr/contributing/contributing.md +++ /dev/null @@ -1,40 +0,0 @@ -# Contributing - -Information about contributing to Lemmy, whether it is translating, testing, designing or programming. - -## Issue tracking / Repositories - -- [GitHub (for issues and pull requests)](https://github.com/LemmyNet/lemmy) -- [Gitea (only for pull requests)](https://yerbamate.ml/LemmyNet/lemmy) -- [Codeberg](https://codeberg.org/LemmyNet/lemmy) - -## Translating - -Check out [Lemmy's Weblate](https://weblate.yerbamate.ml/projects/lemmy/) for translations. You can also help by [translating this documentation](https://github.com/LemmyNet/lemmy-docs#adding-a-new-language). - - -## Architecture - -### Front end - -- The front end is written in `typescript`, using a react-like framework called [inferno](https://infernojs.org/). All UI elements are reusable `.tsx` components. -- The front end repository is [lemmy-ui](https://github.com/LemmyNet/lemmy-ui). -- The routes are at `src/shared/routes.ts`. -- The components are located in `src/shared/components`. - -### Back end - -- The back end is written in `rust`, using `diesel`, and `actix`. -- The server source code is split into main sections in `src`. These include: - - `db` - The low level database actions. - - Database additions are done using diesel migrations. Run `diesel migration generate xxxxx` to add new things. - - `api` - The high level user interactions (things like `CreateComment`) - - `routes` - The server endpoints . - - `apub` - The activitypub conversions. - - `websocket` - Creates the websocket server. - -## Linting / Formatting - -- Every front and back end commit is automatically formatted then linted using `husky`, and `lint-staged`. -- Rust with `cargo fmt` and `cargo clippy`. -- Typescript with `prettier` and `eslint`. diff --git a/src/fr/contributing/docker_development.md b/src/fr/contributing/docker_development.md deleted file mode 100644 index ee035dd..0000000 --- a/src/fr/contributing/docker_development.md +++ /dev/null @@ -1,32 +0,0 @@ -# Docker Development - -## Dependencies (on Ubuntu) - -```bash -sudo apt install git docker-compose -sudo systemctl start docker -git clone https://github.com/LemmyNet/lemmy -``` - -## Running - -```bash -cd docker/dev -./docker_update.sh -``` - -and go to http://localhost:1235. - -*Note: many features (like docs and pictures) will not work without using an nginx profile like that in `ansible/templates/nginx.conf`. - -To speed up the Docker compile, add the following to `/etc/docker/daemon.json` and restart Docker. -``` -{ - "features": { - "buildkit": true - } -} -``` - -If the build is still too slow, you will have to use a -[local build](local_development.md) instead. diff --git a/src/fr/contributing/federation_development.md b/src/fr/contributing/federation_development.md deleted file mode 100644 index fd625d6..0000000 --- a/src/fr/contributing/federation_development.md +++ /dev/null @@ -1,69 +0,0 @@ -# Federation Development - -## Running locally - -Install the dependencies as described in [Docker development](docker_development.md). Then run the following - -```bash -cd docker/federation -./start-local-instances.bash -``` - -The federation test sets up 5 instances: - -Instance | Username | Location | Notes ---- | --- | --- | --- -lemmy-alpha | lemmy_alpha | [127.0.0.1:8540](http://127.0.0.1:8540) | federated with all other instances -lemmy-beta | lemmy_beta | [127.0.0.1:8550](http://127.0.0.1:8550) | federated with all other instances -lemmy-gamma | lemmy_gamma | [127.0.0.1:8560](http://127.0.0.1:8560) | federated with all other instances -lemmy-delta | lemmy_delta | [127.0.0.1:8570](http://127.0.0.1:8570) | only allows federation with lemmy-beta -lemmy-epsilon | lemmy_epsilon | [127.0.0.1:8580](http://127.0.0.1:8580) | uses blocklist, has lemmy-alpha blocked - -You can log into each using the instance name, and `lemmy` as the password, IE (`lemmy_alpha`, `lemmy`). - -To start federation between instances, visit one of them and search for a user, community or post, like this. Note that -the Lemmy backend runs on a different port than the frontend, so you have to increment the port number from -the URL bar by one. -- `!main@lemmy-alpha:8541` -- `http://lemmy-beta:8551/post/3` -- `@lemmy-gamma@lemmy-gamma:8561` - -Firefox containers are a good way to test them interacting. - -## Running on a server - -Note that federation is currently in alpha. **Only use it for testing**, not on any production server, and be aware that turning on federation may break your instance. - -Follow the normal installation instructions, either with [Ansible](../administration/install_ansible.md) or -[manually](../administration/install_docker.md). Then replace the line `image: dessalines/lemmy:v0.x.x` in -`/lemmy/docker-compose.yml` with `image: dessalines/lemmy:federation`. Also add the following in -`/lemmy/lemmy.hjson`: - -``` - federation: { - enabled: true - tls_enabled: true, - allowed_instances: example.com, - } -``` - -Afterwards, and whenever you want to update to the latest version, run these commands on the server: - -``` -cd /lemmy/ -sudo docker-compose pull -sudo docker-compose up -d -``` - -## Security Model - -- HTTP signature verify: This ensures that activity really comes from the activity that it claims -- check_is_apub_valid : Makes sure its in our allowed instances list -- Lower level checks: To make sure that the user that creates/updates/removes a post is actually on the same instance as that post - -For the last point, note that we are *not* checking whether the actor that sends the create activity for a post is -actually identical to the post's creator, or that the user that removes a post is a mod/admin. These things are checked -by the API code, and its the responsibility of each instance to check user permissions. This does not leave any attack -vector, as a normal instance user cant do actions that violate the API rules. The only one who could do that is the -admin (and the software deployed by the admin). But the admin can do anything on the instance, including send activities -from other user accounts. So we wouldnt actually gain any security by checking mod permissions or similar. \ No newline at end of file diff --git a/src/fr/contributing/local_development.md b/src/fr/contributing/local_development.md deleted file mode 100644 index 4cee134..0000000 --- a/src/fr/contributing/local_development.md +++ /dev/null @@ -1,85 +0,0 @@ -### Install build requirements -#### Ubuntu -``` -sudo apt install git cargo libssl-dev pkg-config libpq-dev yarn curl gnupg2 espeak -# install yarn -curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt update && sudo apt install yarn -``` - -#### macOS - -Install Rust using [the recommended option on rust-lang.org](https://www.rust-lang.org/tools/install) (rustup). - -Then, install [Homebrew](https://brew.sh/) if you don't already have it installed. - -Finally, install Node and Yarn. - -``` -brew install node yarn -``` - -### Get the back end source code -``` -git clone https://github.com/LemmyNet/lemmy.git -# or alternatively from gitea -# git clone https://yerbamate.ml/LemmyNet/lemmy.git -``` - -### Build the backend (Rust) -``` -cargo build -# for development, use `cargo check` instead) -``` - -### Get the front end source code -``` -git clone https://github.com/LemmyNet/lemmy-ui.git --recurse-submodules -``` - -### Setup postgresql -#### Ubuntu -``` -sudo apt install postgresql -sudo systemctl start postgresql - -# Either execute db-init.sh, or manually initialize the postgres database: -sudo -u postgres psql -c "create user lemmy with password 'password' superuser;" -U postgres -sudo -u postgres psql -c 'create database lemmy with owner lemmy;' -U postgres -export LEMMY_DATABASE_URL=postgres://lemmy:password@localhost:5432/lemmy -``` - -#### macOS -``` -brew install postgresql -brew services start postgresql -/usr/local/opt/postgres/bin/createuser -s postgres - -# Either execute db-init.sh, or manually initialize the postgres database: -psql -c "create user lemmy with password 'password' superuser;" -U postgres -psql -c 'create database lemmy with owner lemmy;' -U postgres -export LEMMY_DATABASE_URL=postgres://lemmy:password@localhost:5432/lemmy -``` - -### Run a local development instance -``` -cd lemmy -cargo run -``` - -Then open [localhost:1235](http://localhost:1235) in your browser. To reload back-end changes, you will have to rerun `cargo run`. You can use `cargo check` as a faster way to find compilation errors. - -To do front end development: - -``` -cd lemmy-ui -yarn -yarn dev -``` - -and go to [localhost:1234](http://localhost:1234). Front end saves should rebuild the project. - -Note that this setup doesn't include image uploads or link previews (provided by pict-rs and -iframely respectively). If you want to test those, you should use the -[Docker development](docker_development.md). diff --git a/src/fr/contributing/tests.md b/src/fr/contributing/tests.md deleted file mode 100644 index 8f57cb8..0000000 --- a/src/fr/contributing/tests.md +++ /dev/null @@ -1,29 +0,0 @@ -### Tests - -#### Rust - -After installing [local development dependencies](local_development.md), run the -following commands: - -```bash -psql -U lemmy -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;" -./test.sh -``` - -### Federation - -Install the [Local development dependencies](local_development.md), and add the following lines to `/etc/hosts`: - -``` -127.0.0.1 lemmy-alpha -127.0.0.1 lemmy-beta -127.0.0.1 lemmy-gamma -127.0.0.1 lemmy-delta -127.0.0.1 lemmy-epsilon -``` - -Then use the following script to run the tests: -``` -cd api_tests -./run-federation-test.bash -```