context: https://lemmy.ml/post/93984

Issue Summary

These are the problems I encountered trying to follow the guide on join-lemmy.org.

When trying to use docker-compose, I could not get external email delivery working due to the private networking on the main lemmy container. It simply times out when a local address is not used for delivery.

Rather than worry about postfix, I switched to installing from Scratch. Here are the issues I encountered:

• sudo -iu postgres psql -c "CREATE USER lemmy WITH PASSWORD 'db-passwd';" -- This line is missing SUPERUSER. db-init.sh, which is referenced on the configuration page, creates the user with superuser permissions. Without this, a cryptic error "Couldn't run DB Migrations" is displayed, with no further information about the error encountered. I see there might be work towards removing this requirement, but right now, the guide doesn't work as-written.
• cargo install lemmy_server --target-dir /usr/bin [...] This doesn't actually place lemmy_server in /usr/bin. It uses /usr/bin as the target directory for cargo when building. I believe --root is what is meant to be used here. For me, lemmy_server ended up in /root/.cargo/bin/.
• curl -fsSL https://deb.nodesource.com/setup_12.x | sudo -E bash - When finally getting to the yarn install instruction, I learn that at a minimum, Node 14 is required.

I wanted to report these issues I had in hopes that the guide can be improved to help others install Lemmy more easily.

Steps to Reproduce

Try following the guide on a fresh Ubuntu 22.04 server.

broken: https://lemmy.ml/docs/en/index.htmlasd

working: https://rust-lang.github.io/mdBook/cli/index.htmlasd

Its written for a rather obscure distro (Gentoo), and is overly long. I think it would be best to rewrite it from scratch, and for Ubuntu, because everyone can understand that. Besides, iframely should be removed (#92), and Lemmy installed from crates.io (LemmyNet/lemmy#1674).

The Moderation page has the same result listed for "Ban from community" and "Ban from site".

Line 28:
| Ban from community | Ban user from interacting with the community, but can still use the rest of the site. There is also an option to remove all existing posts. | Moderator |

Line 30:
| Ban from site | Ban user from interacting with the community, but can still use the rest of the site. There is also an option to remove all existing posts. | Admin |

I'm not sure what this should say, but it definitely appears to be wrong.

I would like to add some docs, so wanted to build a mdbook to test changes and ran into an error:

❯ cargo install mdbook --git https://github.com/Ruin0x11/mdBook.git \
    --branch localization --rev 9d8147c

   Compiling mdbook v0.4.15 (/Users/saint/.cargo/git/checkouts/mdbook-66041be698320ee6/e74fdb1)
error[E0597]: `local_ctx` does not live long enough
   --> src/renderer/html_handlebars/helpers/navigation.rs:154:25
    |
154 |             t.render(r, &local_ctx, &mut local_rc, out)
    |                         ^^^^^^^^^^ borrowed value does not live long enough
155 |         })?;
    |         -
    |         |
    |         `local_ctx` dropped here while still borrowed
    |         borrow might be used here, when `local_rc` is dropped and runs the destructor for type `handlebars::RenderContext<'_, '_>`
    |
    = note: values in a scope are dropped in the opposite order they are defined

For more information about this error, try `rustc --explain E0597`.
error: could not compile `mdbook` due to previous error
error: failed to compile `mdbook v0.4.15 (https://github.com/Ruin0x11/mdBook.git?branch=localization#e74fdb10)`, intermediate artifacts can be found at `/var/folders/p0/210ryjtx6m1d8jqf0spp6bzc0000gn/T/cargo-installG8D64q`

I am not sure if this is a right project to submit this issue - if not, please let me know.

That way translations could be done via weblate which should be much easier for contributors. Its also a good opportunity to finally upgrade our mdbook version.

https://crates.io/crates/mdbook-i18n-helpers

These are currently available in this Lemmy thread, but a lot of people ask about it, so it seems useful to have it directly in the Lemmy docs (with the ability for different people to make changes, making translations, etc).

It should have a big disclaimer that manual installation is not recommended.

Ideally it should be understandable for someone who hasnt used Reddit or similar sites before, and doesnt know what federation is.

• Update/Community
• Remove/Community
• Delete/Community
• Undo/Remove/Community
• Undo/Delete/Community

It looks like we forgot about those.

As a workaround, before starting the lemmy server:

sudo -iu postgres psql -c “ALTER USER lemmy WITH SUPERUSER;”

It seems that the problematic SQL has been identified in this pull request?

LemmyNet/lemmy@29c4144

This issue is a request to add to the Lemmy Documentation how to setup an instance on a Tor Onion Service (.onion site).

• https://join-lemmy.org/docs/en/index.html

I used Lemmy for the first time today. I went to several different Lemmy Instances in the Tor Browser, and I was surprised that none of them asked me to switch to their .onion site.

I searched the documentation, and I couldn't find anything for queries of onion and tor

It might be the case that the process to point an Onion Service is very simple (install tor and proxy it over localhost). Or it's possible that there's a ton of issues with https redirects or domain name collisions.

In any case, I think the process to setup lemmy behind a Tor Onion Service should be documented. Once that's done, it will likely be adopted by many server admins and this would be a huge boon for the privacy of all lemmy users.

It would be great to have instructions to install lemmy without docker-like environments

The file administation page currently says this:

Lemmy uses roughly 150 MB of RAM in the default Docker installation. CPU usage is negligible.

What about disk usage? I don't know much but I would guess that every post (including images?) would take up disk space in the database?

Or add code for a sample federation block.

Starting with an explanation what each subfolder in crates/ is for.

This means that rust-lang/mdBook#1306 needs to be merged first.

This link works, https://join.lemmy.ml/docs/en/code_of_conduct.html, but it doesn't have the "Where can i find the "Citizen Code of Conduct"? #17" fix. AFAIK, #17 has been fixed, though i know nothing about github.

Nutomic link doesn't work in multiple browsers.
" Nutomic commented 4 days ago

Our code of conduct is here: https://lemmy.ml/docs/en/code_of_conduct.html"

This seems to be the best option for API docs that I can find: https://github.com/juhaku/utoipa

It doesnt support the the pattern with Perform trait for API handlers. This pattern also doesnt serve any purpose in our code as far as I can tell, so I will get rid of it and use simple handler methods instead.

Another disadvantage is that we will have to specify the path separately in utoipa annotations, so the path needs to be present on the method itself, and in api_routes_http.rs. Unfortunately there seems to be no good alternative.

The document goals.md is somewhat unclear. It seems like a TODO list instead of project's goals. The "Resources / Potential Libraries" part would be better in some document in the Contribution section or as a separate document in the same section, e.g. resources.md

• How to build a Docker image and get it on the server
• Necessary to update fork for breaking API changes (Lemmy versions 0.x)
• AGPL license requires making your fork code public

https://lemmy.ml/post/59178

LemmyNet/lemmy#1416 (comment)

As per a discussion in the Lemmy matrix chat room, it became clear that the documentation around Lemmy's configuration file is a little unclear. The "Configuration" page at:

https://lemmy.ml/docs/administration_configuration.html

Makes no mention of "lemmy.hjson", and encourages one to put their configs in to 'config/config.hjson'. The problem comes in when one is not running docker or ansible images and pulls from git, the config/config.hjson file can be overwritten.

The production docker setup apparently mounts lemmy.hjson to config/config.hjson, so regardless what happens with a git update to config/config.hjson, lemmy.hjson doesn't get messed with and gets mounted to where lemmy_server is going to look for it (config/config.hjson). If one is running anything but the docker setup, it's possible this will be unclear and that their config/config.hjson file could be in jeopardy.

So, this feature request is to have the configuration documentation updated to reflect the dangers involved, and possibly to suggest just removing config/config.hjson from the git repository as it should be unnecessary and poses risk to admins. The documentation could also be updated to reflect better the mechanics behind lemmy.hjson being mounted and why it's done that way in the production builds, etc. No mention of lemmy.hjson on the configuration page is probably the biggest omission here.

When viewing the documentation on https://join-lemmy.org/docs/en/, the entry "4.2. API reference" points to https://join-lemmy.org/docs/en/https://join.lemmy.ml/api/index.html.

This seems to be because the link in src/en/SUMMARY.md for [WebSocket API](https://join.lemmy.ml/api/index.html) is interpreted as a local file instead of an actual link when compiling the book. This may be an issue with mdbook though.

https://join-lemmy.org/docs/en/administration/federation_getting_started.html

The federation setup is in the DB now, not the lemmy.hjson

Ideally it should be understandable for someone who hasnt used Reddit or similar sites before, and doesnt know what federation is.

This page https://join-lemmy.org/docs/en/federation/overview.html contains a link to https://join-lemmy.org/docs/en/federation/contributing_apub_api_outline.html which gives a 404 error

The Config File contains a link to https://join-lemmy.org/docs/en/federation/administration.html///instance-allowlist-and-blocklist for a description of Allows and Blocks but it gives a 404 error.

If you shorten it to https://join-lemmy.org/docs/en/federation/administration.html you still get a 404 error

I meant to move this to the developer section because its quite technical for average users. However I forgot that and now the page is missing.

https://github.com/LemmyNet/lemmy-docs/blob/97f6a8552e39bfa4e66322a4e4f17da906a0a98f/src/en/about/ranking.md

I didn't find a link. From:

We will exclude you from interaction if you insult, demean or harass anyone. That is not welcome behavior. We interpret the term “harassment” as including the definition in the Citizen Code of Conduct; if you have any lack of clarity about what might be included in that concept, please read their definition. In particular, we don’t tolerate behavior that excludes people in socially marginalized groups.

Context: LemmyNet/lemmy#2960

I tried to install lemmy via this guide (https://join-lemmy.org/docs/en/administration/install_docker.html), and I'm getting this error when upload any image. SyntaxError: JSON.parse: unexpected character at line 1 column 1 of the JSON data. Server response not is JSON but plain/text with message images_disabled.

Technical details

lemmy install on ubuntu 22.04

Docker Log

lemmy_1 | Starting http server at 0.0.0.0:8536
postgres_1 |
postgres_1 | PostgreSQL Database directory appears to contain a database; Skipping initialization
postgres_1 |
postgres_1 | 2022-08-26 21:43:51.407 UTC [1] LOG: starting PostgreSQL 14.5 on x86_64-pc-linux-musl, compiled by gcc (Alpine 11.2.1_git20220219) 11.2.1 20220219, 64-bit
postgres_1 | 2022-08-26 21:43:51.407 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 5432
pictrs_1 | 2022-08-26T21:43:51.563734Z INFO restructure{store=FileStore { path_gen: "generator", root_dir: "/mnt" }}: pict_rs::store::file_store::restructure: new
postgres_1 | 2022-08-26 21:43:51.407 UTC [1] LOG: listening on IPv6 address "::", port 5432
postgres_1 | 2022-08-26 21:43:51.423 UTC [1] LOG: listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
postgres_1 | 2022-08-26 21:43:51.427 UTC [21] LOG: database system was shut down at 2022-08-26 21:43:43 UTC
pictrs_1 | 2022-08-26T21:43:51.563990Z INFO restructure{store=FileStore { path_gen: "generator", root_dir: "/mnt" }}: pict_rs::store::file_store::restructure: close time.busy=16.5µs time.idle=241µs
postgres_1 | 2022-08-26 21:43:51.434 UTC [1] LOG: database system is ready to accept connections
pictrs_1 | 2022-08-26T21:43:51.564629Z INFO actix_server::builder: Starting 2 workers
pictrs_1 | 2022-08-26T21:43:51.565123Z INFO actix_server::server: Actix runtime found; starting in Actix runtime
lemmy-ui_1 | Inferno is in development mode.
lemmy-ui_1 | httpbase: http://lemmy:8536
lemmy-ui_1 | wsUri: ws://readit.webhop.me/api/v3/ws
lemmy-ui_1 | isHttps: false
lemmy-ui_1 | No JWT cookie found.
lemmy-ui_1 | http://0.0.0.0:1234

Is there a way in the UI to promote another user to admin?

LemmyNet/lemmy#1445

Make it clear that these are just recommendations.

• Set a site description, icon and rules, adjust config/settings
• Add some more admins
• Test that email is working
• Follow Lemmy releases, eg using Github RSS feed
• Join instance admin chat
• Test that federation is working (curl -H 'Accept: application/activity+json' https://your-instance.com/u/your-username should return json, not html)
• Federate with some other instances
• For inclusion on joinlemmy instance list:
  • Federate with at least one instance from the list
  • Should have a site description and icon
  • Wait for us to update the site (there's no fixed schedule for that)
• Promote the instance somehow
• Contribute to Lemmy development (with link to that docs page)

Anything else?

1. To get psql for my docker instead of docker-compose exec postgres psql -U lemmy as is stated in guide, at least in my case I had to use docker-compose exec postgres psql -U username db_name. Otherwise I got errors:
   sudo docker-compose exec postgres psql -U lemmy returns psql: error: FATAL: role "lemmy" does not exist
sudo docker-compose exec postgres psql -U user returns psql: error: FATAL: database "user" does not exist
   So in my case, lemmy is a db name and user - user.

2. When I follow a guide in order to change a domain name and use commands from the guide such as delete from post_aggregates_fast; or insert into post_aggregates_fast select * from post_aggregates_view; I constantly got errors: ERROR: relation "post_aggregates_fast" does not exist .
   Is it outdated info in your guide or there is a problem I should fix? (In my case I have just ignored these errors and domain name was successfully changed).

https://lemmy.ml/docs/en/administration/backup_and_restore.html?highlight=postgres#changing-your-domain-name

Some of the new ones are missing.

https://join.lemmy.ml/docs/en/about/guide.html#sorting

The new version will no longer use IFramely, so we have to remove it from the docs.

The url for the English version of the theming guide is broken:

https://join-lemmy.org/docs/en/client_development/theming.html

I think that this is because the guide is currently saved under /src/en/administration/theming.md, and the expected path is: /src/en/client_development/theming.md

One question that comes up a lot is where to find the mod actions (to delete posts, ban users etc), cause its not that obvious. And there are probably other things worth documenting.

Contributions welcome!

As per this comment the current docker documentation uses files which won't be listed in the main lemmy repo and the "Updating" section points to development files.

It should be updated to use these production files https://github.com/LemmyNet/lemmy-ansible/tree/main/templates

Currently, Lemmy's documentation links to lemmy-js-client. This makes it very difficult to make a client in any language other than JS. I would specifically like to create a Go client.

I think it would be better to have language-agnostic documentation explaining what to send and what the responses will look like. Maybe this documentation can be automatically generated?

When i install new version from docker, with Kradyz guide - i have this problem with compose.

nutomic told me create this isssues :)

nutomic
there was an nginx service added to the docker-compose, i missed that at the time. should either be reverted or needs to be included in upgrade notes.

We have a bunch of different scripts in the Lemmy repo (which I am going to move into a scripts/ subfolder). It would be nice to have a documentation page listing those scripts, and giving a quick explanation what they are for and how to use them.

https://join-lemmy.org/docs/en/administration/install_docker.html

To make Lemmy available outside the server, you need to set up a reverse proxy, like Nginx. You can use the following simple proxy:

Note: If you are planning on running your reverse proxy on port 80, you'll need to update the docker-compose.yml file you just downloaded to change the internal proxy's listening port. If you are setting up Let's Encrypt on the same machine, you'll need to do this.

server {
    listen 80;
    server_name my_domain.tld;

    location / {
        proxy_pass http://localhost:LEMMY_PORT;
        proxy_set_header Host $host;
        include proxy_params;
    }
}

I'm a little confused on this step. What exactly do I need to modify in the docker-compose.yml file, and where does this server block go, in lemmy/nginx.conf or the one in /etc/nginx?

Would it be possible to get an example of what the configuration files should look like after you have certs from Let's Encrypt?

I think this makes sense so that the CoC becomes easier to find, and easier to read. It will also translating it into different languages.

Feature: Move away from Gitbooks
Gitbooks is a proprietary piece of software, and many great alternatives exist.

Recommendations:
Loads of documentation wikis exist but I really like the Jekyll theme: https://github.com/sighingnow/jekyll-gitbook

Maybe some type of creative commons? Or the same AGPL license we use for source code?

Just found this, should be very helpful to avoid broken links.

https://github.com/Michael-F-Bryan/mdbook-linkcheck