calckey/README.md

251 lines
11 KiB
Markdown
Raw Normal View History

2022-12-16 17:35:54 +00:00
<div align="center">
2023-05-05 19:51:26 +00:00
<a href="https://calckey.org/">
2022-12-16 18:44:09 +00:00
<img src="./title_float.svg" alt="Calckey logo" style="border-radius:50%" width="400"/>
</a>
2022-07-19 05:07:59 +00:00
2023-05-05 19:51:26 +00:00
**🌎 **[Calckey](https://calckey.org/)** is an open source, decentralized social media platform that's free forever! 🚀**
2022-07-19 05:07:59 +00:00
2023-01-15 21:07:11 +00:00
[![no github badge](https://nogithub.codeberg.page/badge.svg)](https://nogithub.codeberg.page/)
[![status badge](https://ci.codeberg.org/api/badges/calckey/calckey/status.svg)](https://ci.codeberg.org/calckey/calckey)
2023-05-10 23:59:47 +00:00
[![opencollective badge](https://opencollective.com/calckey/tiers/badge.svg)](https://opencollective.com/Calckey)
2023-01-15 21:07:11 +00:00
[![liberapay badge](https://img.shields.io/liberapay/receives/ThatOneCalculator?logo=liberapay)](https://liberapay.com/ThatOneCalculator)
2022-12-17 18:17:39 +00:00
[![translate-badge](https://hosted.weblate.org/widgets/calckey/-/svg-badge.svg)](https://hosted.weblate.org/engage/calckey/)
2023-01-15 21:07:11 +00:00
[![docker badge](https://img.shields.io/docker/pulls/thatonecalculator/calckey?logo=docker)](https://hub.docker.com/r/thatonecalculator/calckey)
2023-01-04 01:38:07 +00:00
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](./CODE_OF_CONDUCT.md)
2023-02-01 22:18:54 +00:00
[![Codeberg badge](https://custom-icon-badges.demolab.com/badge/hosted%20on-codeberg-4793CC.svg?logo=codeberg&logoColor=white)](https://codeberg.org/calckey/calckey/)
2022-12-16 17:35:54 +00:00
2021-02-07 02:43:55 +00:00
</div>
2021-11-20 09:21:18 +00:00
<div>
2021-03-24 02:57:12 +00:00
2022-11-16 04:25:00 +00:00
<img src="https://pool.jortage.com/voringme/misskey/e7cd2a17-8b23-4e1e-b5cf-709480c623e2.png" align="right" height="320px" alt="Calc (the Calckey mascot) smoking a fat dart"/>
2018-09-12 20:35:11 +00:00
2022-08-08 06:07:22 +00:00
# ✨ About Calckey
- Calckey is based off of Misskey, a powerful microblogging server on ActivityPub with features such as emoji reactions, a customizable web UI, rich chatting, and much more!
2022-08-08 06:07:22 +00:00
- Calckey adds many quality of life changes and bug fixes for users and instance admins alike.
- Read **[this document](./CALCKEY.md)** all for current and future differences.
- Notable differences:
2022-09-14 00:21:23 +00:00
- Improved UI/UX (especially on mobile)
- Improved notifications
- Improved instance security
2022-11-30 02:15:57 +00:00
- Improved accessibility
2023-04-29 20:38:52 +00:00
- Improved threads
2022-08-08 06:07:22 +00:00
- Recommended Instances timeline
2022-10-27 22:30:26 +00:00
- OCR image captioning
2022-09-14 00:21:23 +00:00
- New and improved Groups
2022-11-09 09:04:30 +00:00
- Better intro tutorial
2023-03-17 01:17:53 +00:00
- Compatibility with Mastodon clients/apps
- Backfill user information
2023-03-19 08:32:57 +00:00
- Sonic search
2022-08-08 06:07:22 +00:00
- Many more user and admin settings
2022-09-14 00:21:23 +00:00
- [So much more!](./CALCKEY.md)
2019-02-05 15:13:31 +00:00
2021-11-20 09:21:18 +00:00
</div>
2017-01-23 09:25:52 +00:00
2021-11-20 09:21:18 +00:00
<div style="clear: both;"></div>
2018-04-15 20:04:56 +00:00
2022-08-10 06:14:51 +00:00
# 🥂 Links
2023-05-10 23:59:47 +00:00
- 💸 OpenCollective: <https://opencollective.com/Calckey>
2022-11-19 07:20:18 +00:00
- 💸 Liberapay: <https://liberapay.com/ThatOneCalculator>
- Donate publicly to get your name on the Patron list!
2023-02-01 22:18:54 +00:00
- 🚢 Flagship instance: <https://calckey.social>
- 📣 Official account: <https://i.calckey.cloud/@calckey>
2022-11-06 23:06:44 +00:00
- 💁 Matrix support room: <https://matrix.to/#/#calckey:matrix.fedibird.com>
- 📜 Instance list: <https://calckey.fediverse.observer/list>
- 📖 JoinFediverse Wiki: <https://joinfediverse.wiki/What_is_Calckey%3F>
2022-11-15 06:24:36 +00:00
- 🐋 Docker Hub: <https://hub.docker.com/r/thatonecalculator/calckey>
2022-12-17 18:21:17 +00:00
- ✍️ Weblate: <https://hosted.weblate.org/engage/calckey/>
- 📦 Yunohost: <https://github.com/YunoHost-Apps/calckey_ynh>
2022-08-10 06:14:51 +00:00
2022-11-04 21:38:38 +00:00
# 🌠 Getting started
2022-07-28 02:36:58 +00:00
2022-11-04 21:38:38 +00:00
This guide will work for both **starting from scratch** and **migrating from Misskey**.
2023-01-08 23:49:23 +00:00
## 🔰 Easy installers
2023-01-09 00:23:48 +00:00
If you have access to a server that supports one of the sources below, I recommend you use it! Note that these methods *won't* allow you to migrate from Misskey without manual intervention.
2023-01-05 04:11:34 +00:00
[![Install on Ubuntu](https://pool.jortage.com/voringme/misskey/3b62a443-1b44-45cf-8f9e-f1c588f803ed.png)](https://codeberg.org/calckey/ubuntu-bash-install)  [![Install on the Arch User Repository](https://pool.jortage.com/voringme/misskey/ba2a5c07-f078-43f1-8483-2e01acca9c40.png)](https://aur.archlinux.org/packages/calckey)  [![Install Calckey with YunoHost](https://install-app.yunohost.org/install-with-yunohost.svg)](https://install-app.yunohost.org/?app=calckey)
2023-01-09 00:09:16 +00:00
## 🛳️ Containerization
2023-01-20 00:56:07 +00:00
2023-05-10 23:56:46 +00:00
- [🐳 How to run Calckey with Docker](https://codeberg.org/calckey/calckey/src/branch/develop/docs/docker.md)
- [🛞 How to run Calckey with Kubernetes/Helm](https://codeberg.org/calckey/calckey/src/branch/develop/docs/kubernetes.md)
2023-01-08 23:49:23 +00:00
2023-01-02 15:59:31 +00:00
## 🧑‍💻 Dependencies
2022-11-04 21:46:51 +00:00
2023-05-31 02:37:57 +00:00
- 🐢 At least [NodeJS](https://nodejs.org/en/) v18.16.0 (v20 recommended)
2022-11-27 19:55:45 +00:00
- Install with [nvm](https://github.com/nvm-sh/nvm)
2023-05-31 02:37:57 +00:00
- 🐘 At least [PostgreSQL](https://www.postgresql.org/) v12 (v14 recommende)
2022-12-07 04:42:48 +00:00
- 🍱 At least [Redis](https://redis.io/) v6 (v7 recommend)
2023-05-11 00:08:16 +00:00
- Web Proxy (one of the following)
- 🍀 Nginx (recommended)
2023-05-11 13:25:08 +00:00
- 🦦 Caddy
2023-05-23 00:40:59 +00:00
- 🪶 Apache
2022-11-27 20:04:08 +00:00
### 😗 Optional dependencies
2022-12-17 18:21:17 +00:00
- [FFmpeg](https://ffmpeg.org/) for video transcoding
2023-05-11 00:08:16 +00:00
- Full text search (one of the following)
2023-05-29 16:22:24 +00:00
- 🦔 [Sonic](https://crates.io/crates/sonic-server)
- [MeiliSearch](https://www.meilisearch.com/)
2023-03-19 08:32:17 +00:00
- [ElasticSearch](https://www.elastic.co/elasticsearch/)
2022-11-05 01:48:45 +00:00
### 🏗️ Build dependencies
- 🦀 [Rust toolchain](https://www.rust-lang.org/)
- 🦬 C/C++ compiler & build tools
- `build-essential` on Debian/Ubuntu Linux
- `base-devel` on Arch Linux
2022-11-27 19:55:45 +00:00
- 🐍 [Python 3](https://www.python.org/)
2022-08-08 06:07:22 +00:00
## 👀 Get folder ready
2022-07-27 18:31:56 +00:00
2022-07-19 18:59:20 +00:00
```sh
git clone --depth 1 https://codeberg.org/calckey/calckey.git
2022-07-19 00:36:11 +00:00
cd calckey/
2022-07-27 18:31:56 +00:00
```
2023-05-23 00:40:59 +00:00
> **Note**
2023-05-24 01:03:45 +00:00
> By default, you're on the develop branch. Run `git checkout main` or `git checkout beta` to switch to the Main/Beta branches.
2023-02-09 22:53:32 +00:00
2022-10-27 08:01:27 +00:00
## 📩 Install dependencies
```sh
2023-01-03 23:56:32 +00:00
# nvm install 19 && nvm use 19
2023-01-13 04:54:33 +00:00
corepack enable
corepack prepare pnpm@latest --activate
2023-01-20 00:56:07 +00:00
# To build without TensorFlow, append --no-optional
pnpm i # --no-optional
2022-10-27 08:01:27 +00:00
```
2023-05-07 19:35:46 +00:00
### pm2
To install pm2 run:
```
npm i -g pm2
pm2 install pm2-logrotate
```
2023-05-23 00:40:59 +00:00
> **Note**
> [`pm2-logrotate`](https://github.com/keymetrics/pm2-logrotate/blob/master/README.md) ensures that log files don't infinitely gather size, as Calckey produces a lot of logs.
2023-05-07 19:35:46 +00:00
## 🐘 Create database
2023-05-23 00:40:59 +00:00
In PostgreSQL (`psql`), run the following command:
```sql
CREATE DATABASE calckey WITH encoding = 'UTF8';
```
or run the following from the command line:
```sh
psql postgres -c "create database calckey with encoding = 'UTF8';"
```
2023-03-19 08:32:17 +00:00
In Calckey's directory, fill out the `db` section of `.config/default.yml` with the correct information, where the `db` key is `calckey`.
2023-05-20 03:41:19 +00:00
## 🔎 Set up search
### 🦔 Sonic
Sonic is better suited for self hosters with smaller deployments. It's easier to use, uses almost no resources, and takes barely any any disk space.
2023-03-19 08:32:17 +00:00
Follow sonic's [installation guide](https://github.com/valeriansaliou/sonic#installation)
2023-05-23 00:40:59 +00:00
> **Note**
> If you use IPv4: in Sonic's directory, edit the `config.cfg` file to change `inet` to `"0.0.0.0:1491"`.
2023-03-19 08:32:17 +00:00
In Calckey's directory, fill out the `sonic` section of `.config/default.yml` with the correct information.
2023-05-20 03:41:19 +00:00
### Meilisearch
Meilisearch is better suited for larger deployments. It's faster but uses far more resources and disk space.
Follow Meilisearch's [quick start guide](https://www.meilisearch.com/docs/learn/getting_started/quick_start)
In Calckey's directory, fill out the `meilisearch` section of `.config/default.yml` with the correct information.
### ElasticSearch
Please don't use ElasticSearch unless you already have an ElasticSearch setup and want to continue using it for Calckey. ElasticSearch is slow, heavy, and offers very few benefits over Sonic/Meilisearch.
2023-03-19 08:32:17 +00:00
## 💅 Customize
2022-11-30 18:51:12 +00:00
- To add custom CSS for all users, edit `./custom/assets/instance.css`.
- To add static assets (such as images for the splash screen), place them in the `./custom/assets/` directory. They'll then be available on `https://yourinstance.tld/static-assets/filename.ext`.
2022-11-30 18:51:12 +00:00
- To add custom locales, place them in the `./custom/locales/` directory. If you name your custom locale the same as an existing locale, it will overwrite it. If you give it a unique name, it will be added to the list. Also make sure that the first part of the filename matches the locale you're basing it on. (Example: `en-FOO.yml`)
2023-02-11 21:16:45 +00:00
- To add custom error images, place them in the `./custom/assets/badges` directory, replacing the files already there.
- To add custom sounds, place only mp3 files in the `./custom/assets/sounds` directory.
- To update custom assets without rebuilding, just run `pnpm run gulp`.
2022-11-13 19:32:17 +00:00
## 🧑‍🔬 Configuring a new instance
- Run `cp .config/example.yml .config/default.yml`
- Edit `.config/default.yml`, making sure to fill out required fields.
- Also copy and edit `.config/docker_example.env` to `.config/docker.env` if you're using Docker.
2022-11-04 21:38:38 +00:00
## 🚚 Migrating from Misskey to Calckey
2023-02-20 20:20:47 +00:00
For migrating from Misskey v13, Misskey v12, and Foundkey, read [this document](https://codeberg.org/calckey/calckey/src/branch/develop/docs/migrate.md).
2022-11-04 21:38:38 +00:00
2023-05-11 00:08:16 +00:00
## 🌐 Web proxy
2023-05-11 00:08:16 +00:00
### 🍀 Nginx (recommended)
2022-11-04 21:43:00 +00:00
- Run `sudo cp ./calckey.nginx.conf /etc/nginx/sites-available/ && cd /etc/nginx/sites-available/`
- Edit `calckey.nginx.conf` to reflect your instance properly
- Run `sudo ln -s ./calckey.nginx.conf ../sites-enabled/calckey.nginx.conf`
- Run `sudo nginx -t` to validate that the config is valid, then restart the NGINX service.
2022-11-09 21:38:27 +00:00
2023-05-11 13:25:08 +00:00
### 🦦 Caddy
- Add the following block to your `Caddyfile`, replacing `example.tld` with your own domain:
```caddy
example.tld {
reverse_proxy http://127.0.0.1:3000
}
```
- Reload your caddy configuration
2022-11-04 21:43:00 +00:00
2023-05-23 00:40:59 +00:00
### 🪶 Apache
> **Warning**
> Apache has some known problems with Calckey. Only use it if you have to.
- Run `sudo cp ./calckey.apache.conf /etc/apache2/sites-available/ && cd /etc/apache2/sites-available/`
- Edit `calckey.apache.conf` to reflect your instance properly
- Run `sudo a2ensite calckey.apache` to enable the site
- Run `sudo service apache2 restart` to reload apache2 configuration
2022-08-08 06:07:22 +00:00
## 🚀 Build and launch!
2022-07-27 18:31:56 +00:00
2022-11-27 20:04:08 +00:00
### 🐢 NodeJS + pm2
2022-11-04 21:38:38 +00:00
#### `git pull` and run these steps to update Calckey in the future!
2022-07-27 18:31:56 +00:00
```sh
# git pull
pnpm install
NODE_ENV=production pnpm run build && pnpm run migrate
pm2 start "NODE_ENV=production pnpm run start" --name Calckey
2022-07-19 05:07:59 +00:00
```
2022-07-29 01:25:02 +00:00
2022-11-09 09:52:23 +00:00
## 😉 Tips & Tricks
2022-11-16 04:18:04 +00:00
- When editing the config file, please don't fill out the settings at the bottom. They're designed *only* for managed hosting, not self hosting. Those settings are much better off being set in Calckey's control panel.
- Port 3000 (used in the default config) might be already used on your server for something else. To find an open port for Calckey, run `for p in {3000..4000}; do ss -tlnH | tr -s ' ' | cut -d" " -sf4 | grep -q "${p}$" || echo "${p}"; done | head -n 1`. Replace 3000 with the minimum port and 4000 with the maximum port if you need it.
- I'd recommend you use a S3 Bucket/CDN for Object Storage, especially if you use Docker.
- I'd ***strongly*** recommend against using CloudFlare, but if you do, make sure to turn code minification off.
2023-01-14 21:18:29 +00:00
- For push notifications, run `npx web-push generate-vapid-keys`, then put the public and private keys into Control Panel > General > ServiceWorker.
2022-11-09 21:17:39 +00:00
- For translations, make a [DeepL](https://deepl.com) account and generate an API key, then put it into Control Panel > General > DeepL Translation.
2022-11-15 00:53:08 +00:00
- To add another admin account:
- Go to the user's page > 3 Dots > About > Moderation > turn on "Moderator"
- Go back to Overview > click the clipboard icon next to the ID
- Run `psql -d calckey` (or whatever the database name is)
- Run `UPDATE "user" SET "isAdmin" = true WHERE id='999999';` (replace `999999` with the copied ID)
- Have the new admin log out and log back in