diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index a1163412d..dc333bf9b 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -8,12 +8,14 @@ on: paths: - package.json - apps/** + - !apps/docs/** - libraries/** pull_request: paths: - package.json - apps/** + - !apps/docs/** - libraries/** jobs: diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index e8648af26..34a6ffc7c 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -7,11 +7,13 @@ on: - main paths: - apps/** + - !apps/docs/** - libraries/** pull_request: paths: - apps/** + - !apps/docs/** - libraries/** jobs: diff --git a/.github/workflows/eslint.yaml b/.github/workflows/eslint.yaml index 7e64f6452..4b55adf28 100644 --- a/.github/workflows/eslint.yaml +++ b/.github/workflows/eslint.yaml @@ -8,12 +8,14 @@ on: paths: - package.json - apps/** + - !apps/docs/** - libraries/** pull_request: paths: - package.json - apps/** + - !apps/docs/** - libraries/** jobs: diff --git a/apps/docs/providers/how-to-add-provider.mdx b/apps/docs/developer-guide/how-to-add-provider.mdx similarity index 99% rename from apps/docs/providers/how-to-add-provider.mdx rename to apps/docs/developer-guide/how-to-add-provider.mdx index 87ba7fde4..a813633e2 100644 --- a/apps/docs/providers/how-to-add-provider.mdx +++ b/apps/docs/developer-guide/how-to-add-provider.mdx @@ -169,4 +169,4 @@ You can look at the other integration to understand what data to put inside. And add the new provider to the list. ```typescript show.all.providers.tsx {identifier: 'providerName', component: DefaultImportFromHighOrderProvider}, -``` \ No newline at end of file +``` diff --git a/apps/docs/installation/development.mdx b/apps/docs/installation/development.mdx new file mode 100644 index 000000000..c6e5f9321 --- /dev/null +++ b/apps/docs/installation/development.mdx @@ -0,0 +1,144 @@ +--- +title: Development Environment +--- + +This is currently the recommended option to install Postiz in a supportable configuration. The docker images are in active and heavy development for now. + +## Tested configurations + +- MacOS +- Linux (Fedora 40) + +Naturally you can use these instructions to setup a development environment on any platform, but there may not be much experience in the community to help you with any issues you may encounter. + +## Prerequisites + +This guide will ask you to install & configure several services exaplained below. + +### Prerequisite Cloud Services + +- **[Resend account](https://resend.com)** - for user activation and email notifications. +- **[Cloudflare R2](https://cloudfalre.com)** - for uploads (optional, can use local machine), and storing account data. +- **Social Media API details** - various API keys and secrets (more details later) for services you want to use; reddit, X, Instagram, etc.. + +### Prerequisite Local Services + +- **Node.js** - for running the code! (version 18+) +- **PostgreSQL** - or any other SQL database (instructions beleow suggest Docker) +- **Redis** - for handling worker queues (instructions below suggest Docker) + +We have some messages from users who are using Windows, which should work, but they are not tested well yet. + +## Installation Instructions + +### NodeJS (version 18+) + +A complete guide of how to install NodeJS can be found [here](https://nodejs.org/en/download/). + +### PostgreSQL (or any other SQL database) & Redis + +You can choose **Option A** to **Option B** to install the database. + +#### Option A) Postgres and Redis as Single containers + +You can install [Docker](https://www.docker.com/products/docker-desktop) and run: + +```bash Terminal +docker run -e POSTGRES_USER=root -e POSTGRES_PASSWORD=your_password --name postgres -p 5432:5432 -d postgres +docker run --name redis -p 6379:6379 -d redis +``` + +#### Option B) Postgres and Redis as docker-compose + +Download the [docker-compose.yaml file here](https://raw.githubusercontent.com/gitroomhq/postiz-app/main/docker-compose.dev.yaml), +or grab it from the repository in the next step. + +```bash Terminal +docker compose -f "docker-compose.dev.yaml" up +``` + +## Build Postiz + + + +```bash Terminal +git clone https://github.com/gitroomhq/gitroom +``` + + + +Copy the `.env.example` file to `.env` and fill in the values + +```bash .env +# Required Settings +DATABASE_URL="postgresql://postiz-user:postiz-password@localhost:5432/postiz-db-local" +REDIS_URL="redis://localhost:6379" +JWT_SECRET="random string for your JWT secret, make it long" +FRONTEND_URL="http://localhost:4200" +NEXT_PUBLIC_BACKEND_URL="http://localhost:3000" +BACKEND_INTERNAL_URL="http://localhost:3000" + +# Social Media API Settings +X_API_KEY="Twitter API key for normal oAuth not oAuth2" +X_API_SECRET="Twitter API secret for normal oAuth not oAuth2" +LINKEDIN_CLIENT_ID="Linkedin Client ID" +LINKEDIN_CLIENT_SECRET="Linkedin Client Secret" +REDDIT_CLIENT_ID="Reddit Client ID" +REDDIT_CLIENT_SECRET="Linkedin Client Secret" +GITHUB_CLIENT_ID="GitHub Client ID" +GITHUB_CLIENT_SECRET="GitHub Client Secret" +RESEND_API_KEY="Resend API KEY" +UPLOAD_DIRECTORY="optional: your upload directory path if you host your files locally" +NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY="optional: your upload directory slug if you host your files locally" +CLOUDFLARE_ACCOUNT_ID="Cloudflare R2 Account ID" +CLOUDFLARE_ACCESS_KEY="Cloudflare R2 Access Key" +CLOUDFLARE_SECRET_ACCESS_KEY="Cloudflare R2 Secret Access Key" +CLOUDFLARE_BUCKETNAME="Cloudflare R2 Bucket Name" +CLOUDFLARE_BUCKET_URL="Cloudflare R2 Backet URL" + +# Developer Settings +NX_ADD_PLUGINS=false +IS_GENERAL="true" # required for now +``` + + + + +```bash Terminal +npm install +``` + + + +```bash Terminal +npm run prisma-db-push +``` + + + +```bash Terminal +npm run dev +``` + + + +If everything is running successfully, open http://localhost:4200 in your browser! + +If everything is not running - you had errors in the steps above, please head over to our [support](/support) page. + +## Next Steps + + + + Learn the architecture of the project + + + Set up email for notifications + + + Set up github for authentication and sync + + + Set up providers such as Linkedin, X and Reddit + + diff --git a/apps/docs/installation/docker-compose.mdx b/apps/docs/installation/docker-compose.mdx new file mode 100644 index 000000000..21b01799f --- /dev/null +++ b/apps/docs/installation/docker-compose.mdx @@ -0,0 +1,69 @@ +--- +title: Docker Compose +--- + +import EarlyDoc from '/snippets/earlydoc.mdx'; +import DockerDatabase from '/snippets/docker-database.mdx'; +import DockerEnvvarApps from '/snippets/docker-envvar-apps.mdx'; + + + + +# Example `docker-compose.yml` file + +```yaml +services: + postiz: + image: ghcr.io/gitroomhq/postiz-app:latest + container_name: postiz + restart: always + volumes: + - ./config:/config/ # Should contain your .env file + ports: + - 4200:4200 + - 3000:3000 + networks: + - postiz-network + + postiz-postgres: + image: postgres:14.5 + container_name: postiz-postgres + restart: always + environment: + POSTGRES_PASSWORD: postiz-local-pwd + POSTGRES_USER: postiz-local + POSTGRES_DB: postiz-db-local + volumes: + - postgres-volume:/var/lib/postgresql/data + ports: + - 5432:5432 + networks: + - postiz-network + postiz-pg-admin: + image: dpage/pgadmin4 + container_name: postiz-pg-admin + restart: always + ports: + - 8081:80 + environment: + PGADMIN_DEFAULT_EMAIL: admin@admin.com + PGADMIN_DEFAULT_PASSWORD: admin + networks: + - postiz-network + postiz-redis: + image: redis:7.2 + container_name: postiz-redis + restart: always + ports: + - 6379:6379 + +volumes: + postgres-volume: + external: false + +networks: + postiz-network: + external: false +``` + + diff --git a/apps/docs/installation/docker.mdx b/apps/docs/installation/docker.mdx new file mode 100644 index 000000000..487bf23c2 --- /dev/null +++ b/apps/docs/installation/docker.mdx @@ -0,0 +1,20 @@ +--- +title: Docker +--- + +import EarlyDoc from '/snippets/earlydoc.mdx'; +import DockerDatabase from '/snippets/docker-database.mdx'; +import DockerEnvvarApps from '/snippets/docker-envvar-apps.mdx'; + + + + + + +# Create the container on command line + +```bash +docker create --name postiz -v ./config:/config -p 4200:4200 -p 3000:3000 ghcr.io/postiz/postiz:latest +``` + + diff --git a/apps/docs/installation/kubernetes-helm.mdx b/apps/docs/installation/kubernetes-helm.mdx new file mode 100644 index 000000000..819a64981 --- /dev/null +++ b/apps/docs/installation/kubernetes-helm.mdx @@ -0,0 +1,13 @@ +--- +title: Helm +--- + +import EarlyDoc from '/snippets/earlydoc.mdx'; +import DockerDatabase from '/snippets/docker-database.mdx'; + + + + +Postiz has a helm chart that is in very active development. You can find it here; + +https://github.com/gitroomhq/postiz-helmchart diff --git a/apps/docs/mint.json b/apps/docs/mint.json index 30a445ca8..7fa169e09 100644 --- a/apps/docs/mint.json +++ b/apps/docs/mint.json @@ -61,6 +61,15 @@ "pages": [ "introduction", "quickstart", + { + "group": "Install", + "pages": [ + "installation/development", + "installation/docker", + "installation/docker-compose", + "installation/kubernetes-helm" + ] + }, "howitworks", "emails", "github", @@ -73,9 +82,15 @@ "providers/articles" ] }, - "providers/how-to-add-provider" + "support" ] - } + }, + { + "group": "Developer Guide", + "pages": [ + "developer-guide/how-to-add-provider" + ] + } ], "footerSocials": { "twitter": "https://twitter.com/nevodavid", diff --git a/apps/docs/quickstart.mdx b/apps/docs/quickstart.mdx index 5af8c0afc..c2d7f3e16 100644 --- a/apps/docs/quickstart.mdx +++ b/apps/docs/quickstart.mdx @@ -6,115 +6,13 @@ At the moment it is necessary to build the project locally - some dependencies like redis and postgres can run as docker containers, but there is no docker container for Postiz just yet. -## Prerequisites +## Self Hosted installation options -To run the project you need to have multiple things: +You can choose between the following installation options; -- Node.js (version 18+) -- PostgreSQL (or any other SQL database) -- Redis -- Resend account -- Cloudflare R2 for uploads (optional, can use local machine) -- Social Media Client and Secret (more details later) +* [Development](/installation/development) - The only installation option that is offically supported at the moment. +* [Docker (standalone)](/installation/docker) - Run from the command line with Docker. +* [Docker Compose](/installation/docker-compose) - Run with Docker Compose. +* [Helm](/installation/kubernetes-helm) - Run with Kubernetes + Helm. -### NodeJS (version 18+) -A complete guide of how to install NodeJS can be found [here](https://nodejs.org/en/download/). - -### PostgreSQL (or any other SQL database) & Redis - -Make sure you have PostgreSQL installed on your machine. - -#### Option A) Postgres and Redis as Single containers - -You can install [Docker](https://www.docker.com/products/docker-desktop) and run: - -```bash Terminal -docker run -e POSTGRES_USER=root -e POSTGRES_PASSWORD=your_password --name postgres -p 5432:5432 -d postgres -docker run --name redis -p 6379:6379 -d redis -``` - -#### Option B) Postgres and Redis as docker-compose - -Download the [docker-compose.yaml file here](https://raw.githubusercontent.com/gitroomhq/postiz-app/main/docker-compose.dev.yaml), -or grab it from the repository in the next step. - -```bash Terminal -docker compose -f "docker-compose.dev.yaml" up -``` - -## Build Postiz - - - -```bash Terminal -git clone https://github.com/gitroomhq/gitroom -``` - - - -Copy the `.env.example` file to `.env` and fill in the values - -```bash .env -DATABASE_URL="postgres database URL i.g. postgresql://postiz-local:postiz-local-pwd@0.0.0.0:5432/postiz-db-local" -REDIS_URL="redis database URL" -JWT_SECRET="random string for your JWT secret, make it long" -FRONTEND_URL="By default: http://localhost:4200" -NEXT_PUBLIC_BACKEND_URL="By default: http://localhost:3000" -BACKEND_INTERNAL_URL="If you use docker, you might want something like: http://backend:3000" -X_API_KEY="Twitter API key for normal oAuth not oAuth2" -X_API_SECRET="Twitter API secret for normal oAuth not oAuth2" -LINKEDIN_CLIENT_ID="Linkedin Client ID" -LINKEDIN_CLIENT_SECRET="Linkedin Client Secret" -REDDIT_CLIENT_ID="Reddit Client ID" -REDDIT_CLIENT_SECRET="Linkedin Client Secret" -GITHUB_CLIENT_ID="GitHub Client ID" -GITHUB_CLIENT_SECRET="GitHub Client Secret" -RESEND_API_KEY="Resend API KEY" -UPLOAD_DIRECTORY="optional: your upload directory path if you host your files locally" -NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY="optional: your upload directory slug if you host your files locally" -CLOUDFLARE_ACCOUNT_ID="Cloudflare R2 Account ID" -CLOUDFLARE_ACCESS_KEY="Cloudflare R2 Access Key" -CLOUDFLARE_SECRET_ACCESS_KEY="Cloudflare R2 Secret Access Key" -CLOUDFLARE_BUCKETNAME="Cloudflare R2 Bucket Name" -CLOUDFLARE_BUCKET_URL="Cloudflare R2 Backet URL" -NX_ADD_PLUGINS=false -IS_GENERAL="true" # required for now -``` - - - - -```bash Terminal -npm install -``` - - - -```bash Terminal -npm run prisma-db-push -``` - - - -```bash Terminal -npm run dev -``` - - -You have to follow all the tabs in the "Developers" menu to install Gitroom - - - - Learn the architecture of the project - - - Set up email for notifications - - - Set up github for authentication and sync - - - Set up providers such as Linkedin, X and Reddit - - diff --git a/apps/docs/snippets/docker-database.mdx b/apps/docs/snippets/docker-database.mdx new file mode 100644 index 000000000..babd2cf5b --- /dev/null +++ b/apps/docs/snippets/docker-database.mdx @@ -0,0 +1,6 @@ + +The container images do not yet provide automatic database "installation" +(migrations). This must be done manually outside of the docker containers for now. + +This is being worked on with a high priority. + diff --git a/apps/docs/snippets/docker-envvar-apps.mdx b/apps/docs/snippets/docker-envvar-apps.mdx new file mode 100644 index 000000000..967daf402 --- /dev/null +++ b/apps/docs/snippets/docker-envvar-apps.mdx @@ -0,0 +1,7 @@ +## Controlling container services +The environment variable POSTIZ_APPS defaults to "", which means that all +services will be started in a single container. However, you can only start +specific services within the docker container by changing this environement variable. + +For most deployments, starting all services is fine. To scale out, you might want +to start individual containers for "frontend", "backend", "worker" and "cron". diff --git a/apps/docs/snippets/earlydoc.mdx b/apps/docs/snippets/earlydoc.mdx new file mode 100644 index 000000000..c6ef810ff --- /dev/null +++ b/apps/docs/snippets/earlydoc.mdx @@ -0,0 +1,6 @@ + + **NOTE:** This page is marked "earlydoc", or "early documentation", which means it might + be brief, or contain information about parts of the app that are under heavy development. + If you encounter issues with instructions found here, please check out the [support](/support) + page for options. + diff --git a/apps/docs/_snippets/snippet-example.mdx b/apps/docs/snippets/snippet-example.mdx similarity index 100% rename from apps/docs/_snippets/snippet-example.mdx rename to apps/docs/snippets/snippet-example.mdx diff --git a/apps/docs/support.mdx b/apps/docs/support.mdx new file mode 100644 index 000000000..837f6c860 --- /dev/null +++ b/apps/docs/support.mdx @@ -0,0 +1,35 @@ +--- +title: Support +--- + +Sometimes, things can go wrong, or you need some help! + +Note that the Self Hosted version of Postiz is supported by the community in their +free time, on a best-efforts basis. Please post your question and be patient. + +- [Discord](https://discord.com/invite/sf7QjTcX37) - Flexible chat, with screenshots and screen sharing, probably the best option for support. +- [GitHub issue](https://github.com/gitroomhq/postiz-app/issues/new/choose) - backup option if you are unable to use Discord. + +## How to effectively ask for support + +Try to follow this guide when asking for support, in this order; **Goal, Environment, Changes, Results**. + +- **Goal:** Start off by explaining what you were trying to do + - _I want to schedule a post on Reddit at 6pm_ + - _I want to run in a Linux container on a Raspberry Pi_ + - _I want to use a custom domain name_ + +- **Environment:** - Share the relevant parts about your environment. Web App issues; Are you using Firefox, Chrome, etc? Installation/Other issues; a Mac, Linux, Windows, how did you install? + - _I'm using Firefox on Windows 10_ + - _I'm using a Raspberry Pi 4 with Ubuntu 20.04, and Node version 18_ + - _This is a new installation on a Mac_ + +- **Changed:** - Most likely something has changed, what is it? + - _I updated my browser to the latest version and now ..._ + - _I found a change in the latest version and now ..._ + - _I think this used to work, but now..._ + +- **Results:** - What happened? What did you expect to happen? + - _I see a blank screen_ + - _I see an error message_ + - _I see a 404 page_