|
| 1 | +--- |
| 2 | +title: Self-hosting |
| 3 | +--- |
| 4 | + |
| 5 | +You can get your own PoeticMetric Analytics self-hosted website analytics instance up and running in minutes following this guide. It doesn't require any software development expertise, if you are a little tech-savvy you can do it. PoeticMetric is designed to be self-hosted with Docker, and ready-to-use Docker images are published publicly. |
| 6 | + |
| 7 | +<!-- end --> |
| 8 | + |
| 9 | +If you are curious, there is another documentation article that explains about the parts of PoeticMetric and how these parts communicate with each other. You can check the technical architecture documentation [here](/docs/open-source/technical-architecture). |
| 10 | + |
| 11 | +## Requirements |
| 12 | + |
| 13 | +You will need a server with Docker installed. PoeticMetric has Docker images prebuilt for architectures `linux/amd64` and `linux/arm64`, so make sure your servers CPU is either `x86-64` or `arm64`. |
| 14 | + |
| 15 | +PoeticMetric can run successfully on memory as low as 2GB, however, we recommend allocating at least 4GB of RAM for a smoother experience. However, keep in mind that as the traffic of your website goes up, you might need a more powerful server with a more powerful CPU and more RAM. |
| 16 | + |
| 17 | +<Alert variant="primary"> |
| 18 | + If you don't have a server, you can check it out [Hetzner Cloud](https://hetzner.cloud/?ref=IOqhEJnmxLGq) (referral link), we run our servers on their infrastructure, and we can recommend! |
| 19 | +</Alert> |
| 20 | + |
| 21 | +## Versions |
| 22 | + |
| 23 | +When you follow this tutorial, you will be deploying the latest stable version of PoeticMetric. However, a new version of PoeticMetric will be released with new features from time to time. Don't forget to check the section [Updating to a new version](#updating) before you leave. |
| 24 | + |
| 25 | +PoeticMetric Analytics uses [semantic versioning](https://semver.org): `MAJOR.MINOR.PATCH` |
| 26 | + |
| 27 | +* Updates with a `PATCH` version change (e.g. from `v1.0.0` to `v1.0.1`) include small changes, and mostly, bug fixes. |
| 28 | +* `MINOR` version changing updates (e.g. from `v1.0.8` to `v1.1.0`) include new features, in a backward compatible manner. |
| 29 | +* `MAJOR` version updates include big and important changes, most probably backward incompatible. |
| 30 | + |
| 31 | +Even tough we suggest backing up your data periodically, and especially before performing an update, if you are going for a major version change, please pay extra attention to data backups. |
| 32 | + |
| 33 | +## Running |
| 34 | + |
| 35 | +### Downloading |
| 36 | + |
| 37 | +Start by downloading the required Docker Compose configuration. Download the `self-hosted.zip` file for the [latest release](https://github.com/th0th/poeticmetric/releases/latest), and unzip it: |
| 38 | + |
| 39 | +```shell |
| 40 | +$ curl -fsSL https://github.com/th0th/poeticmetric/releases/latest/download/self-hosted.tar.gz | tar -xz |
| 41 | +$ cd poeticmetric |
| 42 | +``` |
| 43 | + |
| 44 | +### Set environment variables |
| 45 | + |
| 46 | +You will find an `.env.example` file that has all the required environment variables with their default values. First, make a copy of this file with the actual file name: |
| 47 | + |
| 48 | +```shell |
| 49 | +$ cp .env.example .env |
| 50 | +``` |
| 51 | + |
| 52 | +You can leave most of them as they are, however, you will need to change some of them: |
| 53 | + |
| 54 | +#### Internal passwords |
| 55 | + |
| 56 | +These variables will be used for setting the password the relevant component on the first run: |
| 57 | + |
| 58 | +* `CLICKHOUSE_PASSWORD` |
| 59 | +* `POSTGRES_PASSWORD` |
| 60 | +* `RABBITMQ_PASSWORD` |
| 61 | +* `REDIS_PASSWORD` |
| 62 | + |
| 63 | +So, pick a **different**, hard to guess password for each one, and make sure you make note of these. Normally, you won't use any of these passwords while using PoeticMetric. However, if you face any issue, you will need each of them. If you lose one of these passwords, your databases may become inaccessible, and you might lose data. |
| 64 | + |
| 65 | +#### Google Search Console integration variables |
| 66 | + |
| 67 | +`GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are required only for [Google Search Console integration](https://dev.poeticmetric.com/docs/websites/google-search-console-integration). If you are planning to use the integration, you need to obtain them from [Google](https://developers.google.com/webmaster-tools). If you are not planning to use, you can safely skip and leave them as empty. You can also update these variables later. |
| 68 | + |
| 69 | +#### URLs |
| 70 | + |
| 71 | +PoeticMetric has two components that are accessible by HTTP: |
| 72 | + |
| 73 | +* Frontend (`FRONTEND_BASE_URL`) |
| 74 | +* REST API (`REST_API_BASE_URL`) |
| 75 | + |
| 76 | +By the default `docker-compose.yaml`, frontend uses the port `8000`, and REST API `8001`. If you are not going to use a domain name, or a reverse proxy, you should set these as: |
| 77 | + |
| 78 | +`FRONTEND_BASE_URL=http://<your_server_ip_address>:8000` |
| 79 | + |
| 80 | +and |
| 81 | + |
| 82 | +`REST_API_BASE_URL=http://<your_server_ip_address>:8001` |
| 83 | + |
| 84 | +If you are going to use a reverse proxy with a domain name, you need to update the variables `FRONTEND_BASE_URL` and `REST_API_BASE_URL` accordingly, and configure two different virtual servers on your reverse proxy. One for the frontend, pointing to the port `8000`; and another one for the REST API, pointing to the port `8001`. |
| 85 | + |
| 86 | +#### SMTP variables |
| 87 | + |
| 88 | +PoeticMetric requires [Simple Mail Transfer Protocol (SMTP)](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol) for delivering e-mails that are used for notifications, password recovery etc. |
| 89 | + |
| 90 | +Set `SMTP_FROM`, `SMTP_HOST`, `SMTP_PASSWORD`, `SMTP_PORT` and `SMTP_USER` variables according to your e-mail service provider. |
| 91 | + |
| 92 | +### Running services |
| 93 | + |
| 94 | +Once you are done setting up your environment variables, you can bring PoeticMetric's services up by: |
| 95 | + |
| 96 | +```shell |
| 97 | +$ docker compose up -d |
| 98 | +``` |
| 99 | + |
| 100 | +If everything goes well, you should be able to access your self-hosted website analytics instance via the frontend URL you set in the [URLs](#urls) step. Go to `http://<your_frontend_base_url>/bootstrap` to initialize the database schemas, and create your account. |
| 101 | + |
| 102 | +## Updating |
| 103 | + |
| 104 | +When a fresh edition of PoeticMetric becomes available, simply follow these steps: temporarily halt PoeticMetric's services, retrieve the latest docker images, and restart the services. PoeticMetric takes care of updating the databases automatically whenever necessary. |
| 105 | + |
| 106 | +```shell |
| 107 | +$ docker compose down --remove-orphans |
| 108 | +$ docker compose pull |
| 109 | +$ docker compose up -d |
| 110 | +``` |
| 111 | + |
| 112 | +## Getting help |
| 113 | + |
| 114 | +If you have any issues setting up your PoeticMetric Analytics instance, you can ask for community members' help on [GitHub Discussions](https://github.com/th0th/poeticmetric/discussions/new?category=self-hosted-help). |
0 commit comments