### Install Dependencies and Start Dev Server (npm)

Source: https://github.com/umami-software/website/blob/master/README.md

Installs project dependencies using npm and then starts the local development server. This is the standard way to get the Umami website running locally for development.

```shell
# using npm
npm install

npm run dev
```

--------------------------------

### Install Dependencies and Start Dev Server (yarn)

Source: https://github.com/umami-software/website/blob/master/README.md

Installs project dependencies using yarn and then starts the local development server. This provides an alternative method to get the Umami website running locally for development, equivalent to the npm commands.

```shell
# using yarn
yarn

yarn dev
```

--------------------------------

### Start Application (Source Installation)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/install.mdx

Starts the Umami application server. By default, the application will be accessible at http://localhost:3000.

```shell
yarn start
```

--------------------------------

### Run with PM2 (Source Installation)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/install.mdx

Installs PM2 globally, navigates to the Umami directory, starts Umami using PM2 with a specified name, configures PM2 to start processes on boot, and saves the current process list.

```shell
yarn global add pm2
cd umami
pm2 start yarn --name umami -- start
pm2 startup
pm2 save
```

--------------------------------

### Configure Database URL Examples (Source Installation)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/install.mdx

Provides examples of the DATABASE_URL environment variable format for connecting to both PostgreSQL and MySQL databases within the .env configuration file.

```dotenv
DATABASE_URL=postgresql://username:mypassword@localhost:5432/mydb

DATABASE_URL=mysql://username:mypassword@localhost:3306/mydb
```

--------------------------------

### Run Umami with PM2 process manager (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/install.mdx

Installs PM2 globally, navigates to the Umami directory, starts Umami using PM2, configures PM2 to start on boot, and saves the current process list.

```shell
yarn global add pm2
cd umami
pm2 start yarn --name umami -- start
pm2 startup
pm2 save
```

--------------------------------

### Example PostgreSQL Connection URL (Text)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/install.mdx

Provides an example format for the PostgreSQL database connection URL used in the DATABASE_URL environment variable.

```text
postgresql://username:mypassword@localhost:5432/mydb
```

--------------------------------

### Starting Application with Yarn

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/updates.mdx

Starts the application using the start script defined in package.json via Yarn.

```shell
yarn start
```

--------------------------------

### Example MySQL Connection URL (Text)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/install.mdx

Provides an example format for the MySQL database connection URL used in the DATABASE_URL environment variable.

```text
mysql://username:mypassword@localhost:3306/mydb
```

--------------------------------

### Get Source Code and Install Dependencies (Source Installation)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/install.mdx

Clones the Umami repository from GitHub, changes the current directory to the newly cloned repository, and installs all necessary project dependencies using Yarn.

```shell
git clone https://github.com/umami-software/umami.git
cd umami
yarn install
```

--------------------------------

### Start Umami and PostgreSQL with Docker Compose (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/install.mdx

Builds and starts the Umami container along with a PostgreSQL database container using the docker-compose.yml file.

```shell
docker-compose up
```

--------------------------------

### Start with Docker Compose

Source: https://github.com/umami-software/website/blob/master/src/content/docs/install.mdx

Builds (if necessary) and starts the Umami application and a PostgreSQL database container in detached mode using the provided docker-compose configuration.

```shell
docker-compose up -d
```

--------------------------------

### Start Umami application (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/install.mdx

Starts the Umami application in production mode. By default, it runs on http://localhost:3000.

```shell
yarn start
```

--------------------------------

### Perform Initial Umami Setup via SSH - Shell

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/running-on-forge.mdx

Commands to run via SSH on the server after repository installation to install dependencies, update the database schema, and build the project.

```Shell
yarn install
yarn update-db
yarn build
```

--------------------------------

### Installing Dependencies with Yarn

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/updates.mdx

Installs or updates project dependencies based on the package.json file using Yarn.

```shell
yarn install
```

--------------------------------

### Using Umami API Client to Get Websites (JavaScript)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/api-client.mdx

Example demonstrating how to import and use the Umami API client to fetch a list of websites. It shows how to get the client instance and call a method, handling the structured response.

```js
import { getClient } from '@umami/api-client';

const client = getClient();

const { ok, data, status, error } = await client.getWebsites();
```

--------------------------------

### Getting All Websites (Sample Response) - JSON

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/api.mdx

Example JSON response body returned from the GET /api/websites endpoint, providing a list of all tracked websites with their details.

```JSON
[
  {
    "id": 4,
    "websiteUuid": "51f73213-3f01-4343-a135-25496a3ffd31",
    "userId": 2,
    "name": "Umami",
    "domain": "umami.is",
    "shareId": "8PWex1pa",
    "createdAt": "2021-07-26T17:17:52.846Z"
  }
]
```

--------------------------------

### Starting Umami Project with Yarn

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/running-on-planetscale.mdx

Runs the `yarn start` command to start the built Umami project, making it accessible.

```shell
yarn start
```

--------------------------------

### Pulling Umami Docker Image for PostgreSQL

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/getting-started.mdx

Pulls the latest pre-built Docker image for Umami specifically configured to work with a PostgreSQL database from the official Umami Docker registry.

```shell
docker pull docker.umami.is/umami-software/umami:postgresql-latest
```

--------------------------------

### Starting Umami Project with npm

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/running-on-supabase.mdx

Executes the npm start command to start the Umami application after it has been built.

```Shell
npm start
```

--------------------------------

### Pulling Umami Docker Image for MySQL

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/getting-started.mdx

Pulls the latest pre-built Docker image for Umami specifically configured to work with a MySQL database from the official Umami Docker registry.

```shell
docker pull docker.umami.is/umami-software/umami:mysql-latest
```

--------------------------------

### Making API Request with Authentication (Curl Example) - Shell

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/api.mdx

Command-line example using curl to demonstrate how to make a GET request to a Umami API endpoint (/api/websites) while including the required Authorization bearer token header.

```Shell
curl https://yoursever/api/websites
   -H "Accept: application/json"
   -H "Authorization: Bearer <token>"
```

--------------------------------

### Run Standalone Umami v1-v2 Migration Script - Shell

Source: https://github.com/umami-software/website/blob/master/src/content/docs/migrate-v1-v2.mdx

Execute the standalone migration script using yarn start after installing, building, and configuring the database connection in the .env file.

```Shell
yarn start
```

--------------------------------

### Build Application (Source Installation)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/install.mdx

Builds the Umami application from the source code. The first time this command is executed, it also initializes the database schema and creates the default admin user.

```shell
yarn build
```

--------------------------------

### Running Umami with PM2 (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/running-on-digitalocean.mdx

This snippet shows how to install PM2 globally, navigate to the Umami directory, start the Umami process using PM2, and save the process list to ensure it restarts on boot. PM2 is recommended for managing the Umami process.

```shell
npm install pm2 -g
cd umami
pm start npm --name umami -- start
pm save
```

--------------------------------

### Clone Umami repository and install dependencies (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/install.mdx

Clones the Umami source code repository from GitHub, changes the directory into the new repository, and installs project dependencies using Yarn.

```shell
git clone https://github.com/umami-software/umami.git
cd umami
yarn install
```

--------------------------------

### Sample Response for Get Sessions

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/sessions-api.mdx

Example JSON response showing a list of session details for a website within a specified time range, including pagination information.

```json
{
  "data": [
    {
      "id": "5a45d799-e6f5-56ac-9893-fde6f769c36a",
      "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
      "hostname": "umami.is",
      "browser": "chrome",
      "os": "Windows 10",
      "device": "laptop",
      "screen": "1536x960",
      "language": "en-US",
      "country": "US",
      "subdivision1": "US-CA",
      "city": "Roseville",
      "firstAt": "2024-09-09T17:44:35Z",
      "lastAt": "2024-09-09T17:44:35Z",
      "visits": 1,
      "views": 1,
      "createdAt": "2024-09-09T17:44:35Z"
    },
    {
      "id": "753ce23b-0dab-5a33-badc-4d2239528dd9",
      "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
      "hostname": "umami.is",
      "browser": "chrome",
      "os": "Windows 10",
      "device": "desktop",
      "screen": "2560x1440",
      "language": "de-DE",
      "country": "DE",
      "subdivision1": "DE-BY",
      "city": "Munich",
      "firstAt": "2024-09-09T08:54:18Z",
      "lastAt": "2024-09-09T17:44:29Z",
      "visits": 5,
      "views": 66,
      "createdAt": "2024-09-09T17:44:29Z"
    }
  ],
  "count": 1000,
  "page": 1,
  "pageSize": 20
}
```

--------------------------------

### Example UTM Parameter URL

Source: https://github.com/umami-software/website/blob/master/src/content/blog/umami-for-startup-performance-marketing.mdx

An example URL demonstrating the use of UTM parameters (source, medium, campaign) for tracking marketing campaign performance with Umami Analytics.

```text
https://umami.is/lp/demo-link?utm_source=facebook&utm_medium=cpc&utm_campaign=website_analytics
```

--------------------------------

### Configure Database URL Placeholder (Source Installation)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/install.mdx

Shows the basic structure for the DATABASE_URL environment variable in the .env configuration file, indicating where the actual database connection string should be placed.

```dotenv
DATABASE_URL={connection url}
```

--------------------------------

### Fetch Websites with Token (Shell/curl)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/authentication.mdx

Example shell command using curl to make an authenticated GET request to the /api/websites endpoint, demonstrating how to include the Authorization header.

```shell
curl https://{yourserver}/api/websites
   -H "Accept: application/json"
   -H "Authorization: Bearer <token>"
```

--------------------------------

### Install Yarn (Source Installation)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/install.mdx

Installs the Yarn package manager globally using npm, which is a prerequisite for managing dependencies when installing Umami from source.

```shell
npm install -g yarn
```

--------------------------------

### Run Initial Umami Setup Commands via SSH (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/guides/running-on-forge.mdx

Executes the necessary commands via SSH to install dependencies, update the database schema, and build the Umami project after cloning the repository.

```shell
yarn install
yarn update-db
yarn build
```

--------------------------------

### Installing Umami API Client with npm

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/api-client.mdx

Command to install the Umami API client package using npm. This is the first step to integrate the client into a project.

```shell
npm install @umami/api-client
```

--------------------------------

### Sample Response for Get Single Session

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/sessions-api.mdx

Example JSON response detailing information for a specific individual session, including device, location, and activity metrics.

```json
{
  "id": "a35fe227-2fe9-5147-85a0-15f0fd48faed",
  "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
  "hostname": "umami.is",
  "browser": "ios",
  "os": "iOS",
  "device": "mobile",
  "screen": "390x844",
  "language": "en-US",
  "country": "US",
  "subdivision1": "US-IN",
  "city": "Bloomington",
  "firstAt": "2024-09-09T18:12:01Z",
  "lastAt": "2024-09-09T18:12:08Z",
  "visits": 1,
  "views": 3,
  "events": 0,
  "totaltime": 7
}
```

--------------------------------

### Getting Pageviews and Sessions (Sample Response) - JSON

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/api.mdx

Example JSON response body from the GET /api/websites/{websiteUuid}/pageviews endpoint, providing time-series data for pageviews and sessions within a specified range and unit.

```JSON
{
  "pageviews": [
    { "t": "2020-04-20 01:00:00", "y": 3 },
    { "t": "2020-04-20 02:00:00", "y": 7 }
  ],
  "sessions": [
    { "t": "2020-04-20 01:00:00", "y": 2 },
    { "t": "2020-04-20 02:00:00", "y": 4 }
  ]
}
```

--------------------------------

### Install Standalone Umami v1-v2 Migration Script - Shell

Source: https://github.com/umami-software/website/blob/master/src/content/docs/migrate-v1-v2.mdx

Clone the migration script repository, navigate into the directory, and install dependencies and build the script using yarn for standalone execution.

```Shell
git clone https://github.com/umami-software/migrate-v1-v2.git
cd migrate-v1-v2
yarn install
yarn build
```

--------------------------------

### Running Umami with PM2 (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/guides/running-on-digitalocean.mdx

Install PM2 globally and use it to start the Umami application. PM2 is recommended for managing the process, handling restarts, and ensuring the application runs continuously.

```Shell
npm install pm2 -g
cd umami
pm start npm --name umami -- start
pm save
```

--------------------------------

### Build Umami application (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/install.mdx

Builds the Umami application for production. This command also initializes the database and creates the default admin user.

```shell
yarn build
```

--------------------------------

### Getting Metrics (Sample Response) - JSON

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/api.mdx

Example JSON response body from the GET /api/websites/{websiteUuid}/metrics endpoint, providing aggregated data for a specified metric type (like URLs, referrers, etc.) within a time range.

```JSON
[
  { "x": "/", "y": 46 },
  { "x": "/docs", "y": 17 },
  { "x": "/download", "y": 14 }
]
```

--------------------------------

### Standard Umami Tracker Installation HTML

Source: https://github.com/umami-software/website/blob/master/src/content/docs/google-tag-manager.mdx

Shows the standard HTML script tag used to install the Umami tracker directly on a webpage. This method includes `defer` and `data-website-id` attributes.

```html
<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
></script>
```

--------------------------------

### Sample Response for Get Session Stats

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/sessions-api.mdx

Example JSON response providing summarized session statistics for a website, such as pageviews, visitors, visits, countries, and events.

```json
{
  "pageviews": { "value": 3018 },
  "visitors": { "value": 847 },
  "visits": { "value": 984 },
  "countries": { "value": 537 },
  "events": { "value": 150492 }
}
```

--------------------------------

### Creating Website (Sample Response) - JSON

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/api.mdx

Example JSON response body returned after successfully creating a new website via the POST /api/websites endpoint, including details like ID, UUID, name, domain, and share ID.

```JSON
{
  "id": 4,
  "websiteUuid": "51f73213-3f01-4343-a135-25496a3ffd31",
  "userId": 2,
  "name": "Umami",
  "domain": "umami.is",
  "shareId": "8PWex1pa",
  "createdAt": "2021-07-26T17:17:52.846Z"
}
```

--------------------------------

### Getting Events (Sample Response) - JSON

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/api.mdx

Example JSON response body from the GET /api/websites/{websiteUuid}/events endpoint, listing tracked events within a specified time range, including event name, timestamp, and count.

```JSON
[
  { "x": "download-button", "t": "2020-04-20 02:00:00", "y": 2 },
  { "x": "signup-button", "t": "2020-04-20 02:00:00", "y": 1 }
];
```

--------------------------------

### Example URL with UTM Parameters

Source: https://github.com/umami-software/website/blob/master/src/content/docs/guides/measure-campaigns.mdx

An example of a URL with UTM parameters appended to track the source, medium, and campaign.

```Text
https://website.com/?utm_source=newsletter
&utm_medium=email&utm_campaign=sales
```

--------------------------------

### Getting Website Stats (Sample Response) - JSON

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/api.mdx

Example JSON response body from the GET /api/websites/{websiteUuid}/stats endpoint, summarizing key statistics like pageviews, uniques, bounces, and total time for a specified website and time range.

```JSON
{
  "pageviews": { "value": 5, "change": 5 },
  "uniques": { "value": 1, "change": 1 },
  "bounces": { "value": 0, "change": 0 },
  "totaltime": { "value": 4, "change": 4 }
}
```

--------------------------------

### Installing Umami Node Client (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/node-client.mdx

Installs the Umami Node client package using npm. This package allows sending server-side data to your Umami instance.

```Shell
npm install @umami/node
```

--------------------------------

### Updating Umami from Source Code (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/updates.mdx

Provides the sequence of shell commands required to update the Umami application when installed directly from source code. This involves pulling the latest changes, installing dependencies, rebuilding the project, and restarting the application.

```shell
git pull
```

```shell
yarn install
```

```shell
yarn build
```

```shell
yarn start
```

--------------------------------

### Sample JSON Response for Get Team Websites API

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/teams-api.mdx

An example of the JSON structure returned by the GET /api/teams/:teamId/websites endpoint, illustrating the data format for a website object and its associated team and user details.

```json
[
  {
    "id": "40743097-fb48-411c-98bb-efb2aa7d3946",
    "name": "website",
    "domain": "website.com",
    "shareId": "C36MKJqBlRT9UQgq",
    "resetAt": "2023-10-25T17:29:44.340Z",
    "userId": "a36560ed-e21c-4ed9-84aa-c86654460cae",
    "createdAt": "2022-10-07T18:58:52.435Z",
    "updatedAt": "2022-10-25T17:29:44.410Z",
    "deletedAt": null,
    "teamWebsite": [
      {
        "id": "40743097-fb48-411c-98bb-efb2aa7d3946",
        "teamId": "66c8f57c-dec0-46d1-b267-886833d78982",
        "websiteId": "40723097-fb48-411c-98bb-efb2ca7d3946",
        "createdAt": "2022-10-15T16:51:44.711Z",
        "team": {
          "id": "66c8f87c-dec0-46d1-b267-886833d78982",
          "name": "Caoboys",
          "accessCode": "4bwY3JoHUXcKUiMP",
          "createdAt": "2022-04-03T05:50:28.601Z",
          "updatedAt": "2022-09-06T17:08:25.585Z",
          "teamUser": [
            {
              "id": "3509ece6-3f7d-4a45-8842-2c070f1138e3",
              "teamId": "66c8f87c-dec0-46d1-b267-886833d78982",
              "userId": "a36560ed-e21c-4ed9-84aa-c86654460cae",
              "role": "team-owner",
              "createdAt": "2022-04-03T05:50:28.601Z",
              "updatedAt": null
            }
          ]
        }
      }
    ],
    "user": { "id": "a36560ed-e21c-4ed9-84aa-c86654460cae", "username": "admin@website.com" }.
  }
]
```

--------------------------------

### Authorization Header Example (HTTP)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/authentication.mdx

Example of the 'Authorization' header format required for API requests after obtaining a token, using the Bearer scheme.

```http request
Authorization: Bearer eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A
```

--------------------------------

### Building Umami Project with npm

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/running-on-supabase.mdx

Executes the npm run build command to build the Umami project, preparing it for deployment or starting.

```Shell
npm run build
```

--------------------------------

### Example Button Element (Before Umami Class)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/track-events.mdx

An example of a standard HTML button element without any Umami-specific tracking classes applied.

```HTML
<button id="signup-button" class="button">Sign up</button>
```

--------------------------------

### Sample Response for GET /api/websites (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/websites-api.mdx

This JSON snippet provides a sample response body for the GET /api/websites endpoint, illustrating the structure of an array containing website objects returned by the API.

```json
[
  {
    "id": "02d89813-7a72-41e1-87f0-8d668f85008b",
    "name": "My Website",
    "domain": "mywebsite.com",
    "shareId": null,
    "resetAt": null,
    "websiteId": "1a457e1a-121a-11ee-be56-0242ac120002",
    "createdAt": "2023-04-10T23:06:44.250Z",
    "updatedAt": null,
    "deletedAt": null
  }
]
```

--------------------------------

### Install Yarn globally (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/install.mdx

Installs the Yarn package manager globally using npm, which is required for managing project dependencies.

```shell
npm install -g yarn
```

--------------------------------

### Building Project with Yarn

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/updates.mdx

Compiles and builds the project assets using the build script defined in package.json via Yarn.

```shell
yarn build
```

--------------------------------

### Example URL without UTM Parameters

Source: https://github.com/umami-software/website/blob/master/src/content/docs/guides/measure-campaigns.mdx

An example of a standard URL without any tracking parameters appended.

```Text
https://website.com/
```

--------------------------------

### Configure Database Connection URL (Env)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/install.mdx

Sets the DATABASE_URL environment variable in the .env file to specify the database connection string for Umami.

```env
DATABASE_URL=(connection url)
```

--------------------------------

### Example PlanetScale Connection Error

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/running-on-planetscale.mdx

Shows an example error message (`PrismaClientInitializationError`) that might occur if the application cannot reach the database server, often due to network issues or timeouts.

```text
PrismaClientInitializationError: Can't reach database server at `host.aws-region.psdb.cloud`:`3306`
```

--------------------------------

### Configure Database URL in .env

Source: https://github.com/umami-software/website/blob/master/src/content/docs/guides/running-on-neon.mdx

Example configuration for the DATABASE_URL environment variable in the .env file, including the pooled connection string and required pgbouncer parameters.

```text
DATABASE_URL=postgres://user:passwd@endpoint-pooler.region.aws.neon.build/neondb?pgbouncer=true&connect_timeout=10
```

--------------------------------

### Configure Database Connection String - Environment Variable

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/running-on-forge.mdx

Example format for the `DATABASE_URL` environment variable, used to configure the database connection for Umami.

```Environment Variable
DATABASE_URL=mysql://user:password@localhost:3306/dbname
```

--------------------------------

### Configure Forge Daemon to Start Umami Server (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/guides/running-on-forge.mdx

Sets up a Forge daemon to run the `yarn start` command in the Umami project directory, ensuring the Node.js server remains running continuously.

```shell
yarn start
```

--------------------------------

### Add Yarn Build Steps to Forge Deployment Script (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/guides/running-on-forge.mdx

Adds `yarn install` and `yarn build` commands to the Forge deployment script to install dependencies and build the Umami project after pulling the latest code.

```shell
yarn install
yarn build
```

--------------------------------

### Sample Response for Getting User Websites (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/users-api.mdx

Provides a sample JSON array response returned when retrieving websites associated with a user via the GET /api/users/:userId/websites endpoint. Shows a list of website objects.

```json
[
  {
    "id": "02d89813-7a72-41e1-87f0-8d668f85008b",
    "userId": "1a457e1a-121a-11ee-be56-0242ac120002",
    "domain": "mywebsite.com",
    "name": "My Website",
    "shareId": null,
    "createdAt": "2023-04-10T23:06:44.250Z",
    "deletedAt": null,
    "resetAt": null,
    "updatedAt": null
  }
]
```

--------------------------------

### Add Build Steps to Forge Deployment Script - Shell

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/running-on-forge.mdx

Adds `yarn install` and `yarn build` commands to the Forge deployment script after the git pull to build the Umami project.

```Shell
yarn install
yarn build
```

--------------------------------

### Example MySQL Database URL for Umami .env (Dotenv)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/guides/running-on-forge.mdx

Provides an example format for the `DATABASE_URL` environment variable using a MySQL connection string, specifying user, password, host, port, and database name.

```dotenv
DATABASE_URL=mysql://user:password@localhost:3306/dbname
```

--------------------------------

### Sample Response for Get Active Users (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/website-stats-api.mdx

Provides a sample JSON response for the GET /api/websites/:websiteId/active endpoint, showing the number of active users.

```json
{
  "x": 5
}
```

--------------------------------

### Sample Response for Get Pageviews and Sessions (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/website-stats-api.mdx

Provides a sample JSON response for the GET /api/websites/:websiteId/pageviews endpoint, showing time-series data for pageviews and sessions.

```json
{
  "pageviews": [
    { "x": "2020-04-20 01:00:00", "y": 3 },
    { "x": "2020-04-20 02:00:00", "y": 7 }
  ],
  "sessions": [
    { "x": "2020-04-20 01:00:00", "y": 2 },
    { "x": "2020-04-20 02:00:00", "y": 4 }
  ]
}
```

--------------------------------

### Sample Response for Getting All Users (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/users-api.mdx

Provides a sample JSON array response returned when retrieving all users via the GET /api/admin/users endpoint. Requires admin access and shows a list of user objects.

```json
[
  {
    "id:" "1a457e1a-121a-11ee-be56-0242ac120002",
    "username": "umami",
    "role": "admin",
    "createdAt": "2023-04-13T20:22:55.756Z"
  }
]
```

--------------------------------

### Pull Umami Docker image with PostgreSQL support (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/install.mdx

Pulls the latest Umami Docker image specifically built with PostgreSQL database support from the Umami Docker registry.

```shell
docker pull docker.umami.is/umami-software/umami:postgresql-latest
```

--------------------------------

### Get Pooled Connection String with CLI

Source: https://github.com/umami-software/website/blob/master/src/content/docs/guides/running-on-neon.mdx

Command to retrieve the pooled database connection string for a specific Neon project using the Neon CLI.

```bash
npx neonctl connection-string --project-id <project-id> --pooled
```

--------------------------------

### Pulling Latest Docker Image

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/updates.mdx

Downloads the latest Umami Docker image specifically configured for MySQL from the specified registry.

```shell
docker pull docker.umami.is/umami-software/umami:mysql-latest
```

--------------------------------

### Pull Umami Docker image with MySQL support (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/install.mdx

Pulls the latest Umami Docker image specifically built with MySQL database support from the Umami Docker registry.

```shell
docker pull docker.umami.is/umami-software/umami:mysql-latest
```

--------------------------------

### Sample Response for GET /api/websites/:websiteId (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/websites-api.mdx

This JSON snippet provides a sample response body for the GET /api/websites/:websiteId endpoint, showing the structure of a single website object returned when retrieving a website by its ID.

```json
{
  "id": "02d89813-7a72-41e1-87f0-8d668f85008b",
  "name": "My Website",
  "domain": "mywebsite.com",
  "shareId": null,
  "resetAt": null,
  "userId": "1a457e1a-121a-11ee-be56-0242ac120002",
  "createdAt": "2023-04-10T23:06:44.250Z",
  "updatedAt": null,
  "deletedAt": null
}
```

--------------------------------

### Querying Umami Cloud API with cURL

Source: https://github.com/umami-software/website/blob/master/src/content/docs/cloud/api-key.mdx

Demonstrates how to make a GET request to the Umami Cloud API using the curl command-line tool, passing the API key via the custom 'x-umami-api-key' header.

```shell
curl https://api.umami.is/v1/websites
   -H "Accept: application/json"
   -H "x-umami-api-key: <api-key>"
```

--------------------------------

### Sample Response for Getting User by ID (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/users-api.mdx

Provides a sample JSON response returned when retrieving a specific user by their ID via the GET /api/users/:userId endpoint. Shows the user object structure.

```json
{
  "id": "1a457e1a-121a-11ee-be56-0242ac120002",
  "username": "umami",
  "role": "admin"
}
```

--------------------------------

### Configuring Umami with HOSTNAME

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/environment-variables.mdx

Specifies the hostname for the application to bind to, useful in environments like Heroku. Requires starting the app with `npm run start-env`.

```Configuration
HOSTNAME = <hostname>
```

--------------------------------

### Sample Response: GET Session Activity (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/sessions-api.mdx

Provides a sample JSON response for the GET /api/websites/:websiteId/sessions/:sessionId/activity endpoint, showing a list of session activities with details like timestamp, URL path, event type, and event ID.

```json
[
  {
    "createdAt": "2024-09-09T18:12:08Z",
    "urlPath": "/websites/fd4bdd56-2135-4c42-9518-55e72669f23c",
    "urlQuery": "",
    "referrerDomain": "",
    "eventId": "a154aebc-10cf-4a26-8187-c541ef0d2929",
    "eventType": 1,
    "eventName": "",
    "visitId": "609a5116-b139-5c6d-9293-fbea9b8a3b61"
  },
  {
    "createdAt": "2024-09-09T18:12:01Z",
    "urlPath": "/settings/websites",
    "urlQuery": "",
    "referrerDomain": "",
    "eventId": "92246b7b-e3e2-4c9d-b61e-fab69d993ad7",
    "eventType": 1,
    "eventName": "",
    "visitId": "609a5116-b139-5c6d-9293-fbea9b8a3b61"
  }
]
```

--------------------------------

### Sample Response for Get Event Series (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/website-stats-api.mdx

Provides a sample JSON array response for the GET /api/websites/:websiteId/events/series endpoint, detailing event occurrences over time.

```json
[
  { "x": "live-demo-button", "t": "2023-04-12T22:00:00Z", "y": 1 },
  { "x": "get-started-button", "t": "2023-04-12T22:00:00Z", "y": 5 },
  { "x": "get-started-button", "t": "2023-04-12T23:00:00Z", "y": 4 },
  { "x": "live-demo-button", "t": "2023-04-12T23:00:00Z", "y": 4 },
  { "x": "social-Discord", "t": "2023-04-13T00:00:00Z", "y": 1 }
]
```

--------------------------------

### Sample Response for Get Website Statistics Summary (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/website-stats-api.mdx

Provides a sample JSON response for the GET /api/websites/:websiteId/stats endpoint, summarizing key website metrics like pageviews, visitors, visits, bounces, and total time.

```json
{
  "pageviews": { "value": 3018, "prev": 3508 },
  "visitors": { "value": 847, "prev": 910 },
  "visits": { "value": 984, "prev": 1080 },
  "bounces": { "value": 537, "prev": 628 },
  "totaltime": { "value": 150492, "prev": 164713 }
}
```

--------------------------------

### Pull PostgreSQL Docker Image

Source: https://github.com/umami-software/website/blob/master/src/content/docs/install.mdx

Pulls the latest pre-built Umami Docker image from the registry that is specifically configured for use with a PostgreSQL database.

```shell
docker pull docker.umami.is/umami-software/umami:postgresql-latest
```

--------------------------------

### Umami Tracker Installation for Google Tag Manager JavaScript

Source: https://github.com/umami-software/website/blob/master/src/content/docs/google-tag-manager.mdx

Provides a JavaScript workaround for installing the Umami tracker when using Google Tag Manager. It dynamically creates the script element and sets attributes because GTM might strip them from standard HTML tags.

```javascript
<script>
  (function () {
  var el = document.createElement('script');
  el.setAttribute('src', 'http://mywebsite.com/script.js');
  el.setAttribute('data-website-id', '94db1cb1-74f4-4a40-ad6c-962362670409');
  document.body.appendChild(el);
})();
</script>
```

--------------------------------

### Deploying Umami App on Koyeb

Source: https://github.com/umami-software/website/blob/master/src/content/docs/guides/running-on-koyeb.mdx

This command initializes a new Koyeb application named 'umami'. It specifies the Docker image to use, maps internal port 3000 to external HTTP traffic, routes the root path '/' to port 3000, and sets the DATABASE_URL environment variable using the previously created secret.

```Shell
koyeb app init umami --docker docker.umami.is/umami-software/umami:postgresql-latest --ports 3000:http --routes /:3000 --env DATABASE_URL=@umami-database-url
```

--------------------------------

### Sample Response: GET Session Properties (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/sessions-api.mdx

Provides a sample JSON response for the GET /api/websites/:websiteId/sessions/:sessionId/properties endpoint, showing a list of custom session properties with their key, type, and value.

```json
[
  {
    "websiteId": "1ccddccf-7d34-432b-84e6-e46903b2acf3",
    "sessionId": "a35fe227-2fe9-5147-85a0-15f0fd48faed",
    "dataKey": "email",
    "dataType": 1,
    "stringValue": "johndoe@gmail.com",
    "numberValue": null,
    "dateValue": null,
    "createdAt": "2024-09-09T18:12:01Z"
  },
  {
    "websiteId": "1ccddccf-7d34-432b-84e6-e46903b2acf3",
    "sessionId": "a35fe227-2fe9-5147-85a0-15f0fd48faed",
    "dataKey": "name",
    "dataType": 1,
    "stringValue": "John Doe",
    "numberValue": null,
    "dateValue": null,
    "createdAt": "2024-09-09T18:12:01Z"
  }
]
```

--------------------------------

### Configuring Umami with PORT

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/environment-variables.mdx

Specifies the port number for the application to bind to, useful in environments like Heroku. Requires starting the app with `npm run start-env`.

```Configuration
PORT = <port number>
```

--------------------------------

### Deploying Umami App on Koyeb using Koyeb CLI

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/running-on-koyeb.mdx

This command initializes a new Koyeb application named 'umami'. It specifies the Docker image to use, maps internal port 3000 to external HTTP traffic, defines the root route ('/') to forward to port 3000, and sets the DATABASE_URL environment variable by referencing the previously created Koyeb secret.

```shell
koyeb app init umami --docker docker.umami.is/umami-software/umami:postgresql-latest --ports 3000:http --routes /:3000 --env DATABASE_URL=@umami-database-url
```

--------------------------------

### Sample Response for Getting User Teams (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/users-api.mdx

Provides a sample JSON array response returned when retrieving teams associated with a user via the GET /api/users/:userId/teams endpoint. Shows a list of team objects.

```json
[
  {
    "id": "02d89813-7a72-41e1-87f0-8d668f85008b",
    "name": "My Team",
    "createdAt": "2023-04-10T23:06:44.250Z",
    "deletedAt": null,
    "updatedAt": null
  }
]
```

--------------------------------

### Login Response Body (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/authentication.mdx

Example JSON response received upon successful authentication via POST /api/auth/login, containing the authentication token and user details.

```json
{
  "token": "eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A",
  "user": {
    "id": "cd33a605-d785-42a1-9365-d6cad3b7befd",
    "username": "your-username",
    "createdAt": "2020-04-20 01:00:00"
  }
}
```

--------------------------------

### Pull MySQL Docker Image

Source: https://github.com/umami-software/website/blob/master/src/content/docs/install.mdx

Pulls the latest pre-built Umami Docker image from the registry that is specifically configured for use with a MySQL database.

```shell
docker pull docker.umami.is/umami-software/umami:mysql-latest
```

--------------------------------

### API Client Methods for Website Management (Mapping)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/api-client.mdx

Mapping of API client methods for managing websites to their corresponding HTTP methods and API endpoints. Includes operations for getting, creating, updating, and deleting websites, and accessing website-specific data like active users, events, metrics, and stats.

```text
getWebsites() ⇒ GET /websites
createWebsite(data) ⇒ POST /websites
getWebsite(id) ⇒ GET /websites/{id}
updateWebsite(id, data) ⇒ POST /websites/{id}
deleteWebsite(id) ⇒ DEL /websites/{id}
getWebsiteActive(id) ⇒ GET /websites/{id}/active
getWebsiteEvents(id, data) ⇒ GET /websites/{id}/events
getWebsiteMetrics(id, data) ⇒ GET /websites/{id}/metrics
getWebsitePageviews(id, data) ⇒ GET /websites/{id}/pageviews
resetWebsite(id) ⇒ GET /websites/{id}/reset
getWebsiteStats(id, data) ⇒ GET /websites/{id}/stats
```

--------------------------------

### Pulling Latest Source Code

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/updates.mdx

Updates the local repository with the latest changes from the remote Git repository.

```shell
git pull
```

--------------------------------

### Login Request Body (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/authentication.mdx

Example JSON payload required for the POST /api/auth/login endpoint to authenticate a user with username and password.

```json
{
  "username": "your-username",
  "password": "your-password"
}
```

--------------------------------

### Authenticating with Umami API (Request Body) - JSON

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/api.mdx

Example JSON payload required for the POST /api/auth/login endpoint to obtain an authentication token using username and password.

```JSON
{
  "username": "your-username",
  "password": "your-password"
}
```

--------------------------------

### Sample Response for GET Event Data Stats - JSON

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/events-api.mdx

Provides a sample JSON response summarizing website events, fields, and records within a given time range.

```json
[{ "events": 16, "fields": 13, "records": 26 }]
```

--------------------------------

### Configuring HOSTNAME and PORT Environment Variables (dotenv)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/environment-variables.mdx

Specifies the hostname and port for the application to bind to, useful for environments like Heroku. Requires starting the app with npm run start-env.

```dotenv
HOSTNAME = "my.hostname.com"
PORT = 3000
```

--------------------------------

### Sample Response for GET Events - JSON

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/events-api.mdx

Provides a sample JSON response structure for retrieving website event details within a time range, including event properties like ID, website ID, session ID, timestamp, URL, referrer, page title, event type, and event name.

```json
{
  "data": [
    {
      "id": "dbcfe5ef-99f4-44e1-ad3f-c157eb102a13",
      "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
      "sessionId": "970c97c5-2071-540a-be88-098eb730ccac",
      "createdAt": "2024-09-06T23:36:44Z",
      "urlPath": "/docs/api/authentication",
      "urlQuery": "",
      "referrerPath": "/docs/api",
      "referrerQuery": "",
      "referrerDomain": "",
      "pageTitle": "Overview – Umami",
      "eventType": 1,
      "eventName": ""
    },
    {
      "id": "9ba0da36-136b-4fef-afae-a5cdba78017b",
      "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
      "sessionId": "466cb31d-8cda-5dc3-9dd2-b259f29551a5",
      "createdAt": "2024-09-06T23:36:33Z",
      "urlPath": "/",
      "urlQuery": "utm_source=apollo&utm_medium=outbound-email&utm_campaign=founders",
      "referrerPath": "",
      "referrerQuery": "",
      "referrerDomain": "",
      "pageTitle": "Umami",
      "eventType": 1,
      "eventName": ""
    }
  ],
  "count": 1000,
  "page": 1,
  "pageSize": 20
}
```

--------------------------------

### Initializing and Tracking with Umami Node Client (JavaScript)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/node-client.mdx

Demonstrates how to initialize the Umami Node client with your website ID and host URL, and then track a page view using the `.track` function.

```JavaScript
import umami from '@umami/node';

umami.init({
  websiteId: '50429a93-8479-4073-be80-d5d29c09c2ec', // Your website id
  hostUrl: 'https://umami.mywebsite.com', // URL to your Umami instance
});

umami.track({ url: '/home' });
```

--------------------------------

### Verify Token Response Body (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/authentication.mdx

Example JSON response received from the POST /api/auth/verify endpoint, indicating the validity of the token and providing user details.

```json
{
  "id": "1a457e1a-121a-11ee-be56-0242ac120002",
  "username": "umami",
  "role": "admin",
  "isAdmin": true
}
```

--------------------------------

### Building Umami Project with Yarn

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/running-on-planetscale.mdx

Runs the `yarn build` command to build the Umami project, preparing it for production deployment.

```shell
yarn build
```

--------------------------------

### Button Element with Umami CSS Tracking Class

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/track-events.mdx

The example button element with the umami--click--signup-button class added. This class tells Umami to track a 'click' event named 'signup-button' when the button is clicked.

```HTML
<button id="signup-button" class="button umami--click--signup-button">Sign up</button>
```

--------------------------------

### Track Event Using JavaScript window.umami

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/track-events.mdx

Example JavaScript code to manually track an event using the window.umami object. It gets the button element and attaches a click handler that calls umami() with the desired event name. This records a 'custom' event.

```JavaScript
const button = document.getElementById('signup-button');

button.onclick = () => umami('Signup button click');
```

--------------------------------

### Updating Umami via Docker (Shell)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/updates.mdx

Shows the shell commands to pull the latest Docker image for Umami, depending on the database configuration (PostgreSQL or MySQL). This is the method for updating when using the official Docker images.

```shell
docker pull docker.umami.is/umami-software/umami:postgresql-latest
```

```shell
docker pull docker.umami.is/umami-software/umami:mysql-latest
```

--------------------------------

### Authenticating with Umami API (Successful Response) - JSON

Source: https://github.com/umami-software/website/blob/master/src/content/docs/v1/api.mdx

Example JSON response received upon successful authentication via the POST /api/auth/login endpoint, containing the necessary bearer token for subsequent API requests.

```JSON
{
  "token": "eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A"
}
```

--------------------------------

### Access Umami Docker Container Shell - Shell

Source: https://github.com/umami-software/website/blob/master/src/content/docs/migrate-v1-v2.mdx

Execute a docker command to get an interactive shell session inside the running Umami application container as the root user (u 0) to prepare for running the migration script within Docker.

```Shell
docker exec -ti -u 0 <app container name> sh
```

--------------------------------

### Sample Response for POST /api/websites (JSON)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/websites-api.mdx

This JSON snippet shows a sample response body for the POST /api/websites endpoint, demonstrating the structure of the newly created website object returned upon successful creation.

```json
{
  "id": 4,
  "websiteUuid": "51f73213-3f01-4343-a135-25496a3ffd31",
  "websiteId": 2,
  "name": "Umami",
  "domain": "umami.is",
  "shareId": "8PWex1pa",
  "createdAt": "2021-07-26T17:17:52.846Z"
}
```

--------------------------------

### Create Neon Project with CLI

Source: https://github.com/umami-software/website/blob/master/src/content/docs/guides/running-on-neon.mdx

Command to create a new Neon Postgres project using the Neon CLI.

```bash
npx neonctl projects create
```

--------------------------------

### API Client Methods for User Management (Mapping)

Source: https://github.com/umami-software/website/blob/master/src/content/docs/api/api-client.mdx

Mapping of API client methods for managing users to their corresponding HTTP methods and API endpoints. Includes operations like getting, creating, updating, and deleting users, and accessing user-specific data.

```text
getUsers() ⇒ GET /users
createUser(data) ⇒ POST /users
getUser(id) ⇒ GET /users/{id}
updateUser(id, data) ⇒ POST /users/{id}
deleteUser(id) ⇒ DEL /users/{id}
getUserWebsites(id) ⇒ GET /users/{id}/websites
getUserUsage(id, data) ⇒ GET /users/{id}/usage
```