Skip to content

Commit c529ed3

Browse files
OrkuncakilkayaOrkuncakilkaya
authored
Merge pull request #1 from fingerprintjs/polish-repository-inter-1338
refactor: polish repository for public visibility
2 parents ad71c9e + 2431a48 commit c529ed3

File tree

16 files changed

+347
-61
lines changed

16 files changed

+347
-61
lines changed

‎.git_hooks/commit-msg

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#!/usr/bin/env sh
2+
3+
npx commitlint --edit $1

‎.github/CODEOWNERS

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Users referenced in this file will automatically be requested as reviewers for PRs that modify the given paths.
2+
# See https://help.github.com/articles/about-code-owners/
3+
4+
* @Orkuncakilkaya

‎.github/workflows/analyze-commits.yml

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name: Analyze Commit Messages
2+
on:
3+
pull_request:
4+
5+
permissions:
6+
pull-requests: write
7+
contents: write
8+
jobs:
9+
analyze-commits:
10+
name: Generate docs and coverage report
11+
uses: fingerprintjs/dx-team-toolkit/.github/workflows/analyze-commits.yml@v1

‎.github/workflows/create-pr.yml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
name: Create PR (for main and rc)
2+
3+
on:
4+
release:
5+
types:
6+
- published
7+
8+
jobs:
9+
create-pr:
10+
name: Create PR
11+
uses: fingerprintjs/dx-team-toolkit/.github/workflows/create-pr.yml@v1
12+
with:
13+
target_branch: ${{ github.event.release.prerelease && 'main' || 'rc' }}
14+
tag_name: ${{ github.event.release.tag_name }}
15+
prerelease: ${{ github.event.release.prerelease }}

‎.github/workflows/release.yml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: release
2+
on:
3+
push:
4+
branches:
5+
- main
6+
- rc
7+
8+
jobs:
9+
build-and-release:
10+
name: 'Build project, run CI checks and publish new release'
11+
uses: fingerprintjs/dx-team-toolkit/.github/workflows/release-server-sdk.yml@v1
12+
with:
13+
language: terraform
14+
language-version: 1.9.4
15+
appId: ${{ vars.APP_ID }}
16+
secrets:
17+
APP_PRIVATE_KEY: ${{ secrets.APP_PRIVATE_KEY }}

‎.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,6 @@ override.tf.json
1111
.terraformrc
1212
terraform.rc
1313
.idea
14-
1514
assets
15+
examples/**/*.lock.hcl
16+
.DS_Store

‎.releaserc

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
{
2+
"branches": [
3+
"main",
4+
{
5+
"name": "rc",
6+
"prerelease": true
7+
}
8+
],
9+
"plugins": [
10+
[
11+
"@semantic-release/commit-analyzer",
12+
{
13+
"config": "@fingerprintjs/conventional-changelog-dx-team",
14+
"releaseRules": "@fingerprintjs/conventional-changelog-dx-team/release-rules"
15+
}
16+
],
17+
[
18+
"@semantic-release/release-notes-generator",
19+
{
20+
"config": "@fingerprintjs/conventional-changelog-dx-team"
21+
}
22+
],
23+
"@semantic-release/changelog",
24+
[
25+
"@semantic-release/exec",
26+
{
27+
"prepareCmd": "./scripts/preparePackage.sh"
28+
}
29+
],
30+
[
31+
"@semantic-release/git",
32+
{
33+
"message": "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}",
34+
"assets": [
35+
"CHANGELOG.md"
36+
]
37+
}
38+
],
39+
[
40+
"@semantic-release/github",
41+
{
42+
"assets": [
43+
{
44+
"path": "package.zip"
45+
}
46+
]
47+
}
48+
]
49+
]
50+
}

‎CONTRIBUTING.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Contributing to Fingerprint Fastly VCL Integration Terraform Module
2+
3+
## Working with code
4+
5+
6+
For proposing changes, use the standard [pull request approach](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). It's recommended to discuss fixes or new functionality in the Issues, first.
7+
8+
* The `main` and `rc` branches are locked for the push action.
9+
* Releases are created from the `main` branch. If you have Fastly VCL Integration set up, it is running code from the `main` branch. Pull requests into the `main` branch are not accepted.
10+
* The `rc` branch functions as a candidate for the next release. Create your pull requests into this branch. The code in `rc` must always pass the tests.
11+
12+
### Code style
13+
14+
Consistent code formatting is enforced by [TFLint](https://github.com/terraform-linters/tflint) and [Prettier](https://prettier.io/).
15+
16+
### Security scans
17+
18+
We are using [Trivy](https://aquasecurity.github.io/trivy/v0.47/tutorials/misconfiguration/terraform/) to do security scans for us.
19+
20+
### Commit style
21+
22+
You are required to follow [conventional commits](https://www.conventionalcommits.org) rules.
23+
24+
### How to test
25+
26+
We manually test the implementation.
27+
28+
### How to release a new version
29+
30+
Every PR should target `rc` branch first. Upon merge, if there are relevant changes a new release candidate is created.
31+
When that happens, an automated PR is created to `main` branch, and E2E tests run against it. If the tests pass, the PR can be merged and the release is created.
32+
33+
The integration is automatically released on every push to the main branch if there are relevant changes. The workflow must be approved by one of the maintainers, first.
34+
35+
## How to test without DNS and TLS Setup
36+
37+
To test terraform module on your Fastly VCL service, you can use Fastly subdomain `.global.prod.fastly.net`. See example below:
38+
39+
```terraform
40+
module "fingerprint_fastly_vcl_integration" {
41+
# ...
42+
integration_domain = "mydomain.com" # <- Your test domain will be this: `https://mydomain.com.global.prod.fastly.net`
43+
}
44+
```
45+
46+
Then you can visit your domain preview with this URL: [https://mydomain.com.global.prod.fastly.net](https://mydomain.com.global.prod.fastly.net)
47+
48+
## How test using Fingerprint Staging Environment
49+
50+
To test terraform module using Fingerprint's staging environment, you need to [customize your VCL asset](https://github.com/fingerprintjs/fingerprint-pro-fastly-vcl-integration?tab=readme-ov-file#customizing-the-template).
51+
52+
- Clone [Fingerprint VCL Integration](https://github.com/fingerprintjs/fingerprint-pro-fastly-vcl-integration) repository.
53+
```shell
54+
git clone git@github.com:fingerprintjs/fingerprint-pro-fastly-vcl-integration.git
55+
cd fingerprint-pro-fastly-vcl-integration
56+
pnpm install
57+
```
58+
- Build your own VCL file:
59+
```shell
60+
pnpm build --fpcdn-domain "procdn.fpjs.sh" --fpjs-domain "api.stage.fpjs.sh"
61+
```
62+
- [Use your own custom asset](./README.md#custom-vcl) to deploy your integration
63+

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Fingerprint
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 120 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,138 @@
1-
# Prerequisites
1+
<p align="center">
2+
<a href="https://fingerprint.com">
3+
<picture>
4+
<source media="(prefers-color-scheme: dark)" srcset="https://fingerprintjs.github.io/home/resources/logo_light.svg" />
5+
<source media="(prefers-color-scheme: light)" srcset="https://fingerprintjs.github.io/home/resources/logo_dark.svg" />
6+
<img src="https://fingerprintjs.github.io/home/resources/logo_dark.svg" alt="Fingerprint logo" width="312px" />
7+
</picture>
8+
</a>
9+
</p>
10+
11+
<p align="center">
12+
<a href="https://registry.terraform.io/modules/fingerprintjs/vcl-fingerprint-proxy-integration/fastly/latest"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.terraform.io%2Fv2%2Fmodules%2Ffingerprintjs%2Fvcl-fingerprint-proxy-integration%2Ffastly%3Finclude%3Dlatest-version&query=%24.included%5B0%5D.attributes.version&prefix=v&label=Terraform" alt="Current version"></a>
13+
<a href="https://github.com/fingerprintjs/terraform-fastly-vcl-fingerprint-proxy-integration"><img src="https://img.shields.io/github/v/release/fingerprintjs/terraform-fastly-vcl-fingerprint-proxy-integration" alt="Current version"></a>
14+
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/:license-mit-blue.svg" alt="MIT license"></a>
15+
<a href="https://discord.gg/39EpE2neBg"><img src="https://img.shields.io/discord/852099967190433792?style=logo&label=Discord&logo=Discord&logoColor=white" alt="Discord server"></a>
16+
</p>
17+
18+
# Fingerprint Fastly VCL Integration (Terraform module)
19+
20+
[Fingerprint](https://fingerprint.com/) is a device intelligence platform offering industry-leading accuracy.
21+
22+
Fingerprint Fastly VCL Integration is responsible for
23+
24+
- Proxying download requests of the latest Fingerprint JS Agent between your site and Fingerprint CDN.
25+
- Proxying identification requests and responses between your site and Fingerprint's APIs.
26+
27+
This [improves](https://dev.fingerprint.com/docs/fastly-vcl-proxy-integration#the-benefits-of-using-the-fastly-vcl-proxy-integration) both accuracy and reliability of visitor identification and bot detection on your site.
28+
29+
You can install the Fastly VCL proxy integration [manually](https://dev.fingerprint.com/docs/deploy-fastly-vcl-manually) or as [a Terraform module](https://registry.terraform.io/modules/fingerprintjs/vcl-fingerprint-proxy-integration/fastly/latest) included in this repository. For more details, see the [full documentation](https://dev.fingerprint.com/docs/fastly-vcl-proxy-integration).
30+
31+
32+
## Requirements
33+
34+
- [Fastly](https://www.fastly.com/signup) Account
35+
- [Terraform CLI](https://developer.hashicorp.com/terraform/install).
36+
- [Fastly API Token](https://manage.fastly.com/account/tokens)
37+
38+
> [!IMPORTANT]
39+
> The Fastly VCL Proxy Integration is exclusively supported for customers on the Enterprise Plan. Other customers are encouraged to use [Custom subdomain setup](https://dev.fingerprint.com/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](https://dev.fingerprint.com/docs/cloudflare-integration).
40+
41+
> [!WARNING]
42+
> The underlying data contract in the identification logic can change to keep up with browser updates. Using the Fastly VCL Proxy Integration might require occasional manual updates on your side. Ignoring these updates will lead to lower accuracy or service disruption.
43+
44+
## 1. Install the Terraform module
45+
46+
1. Add the module to your Terraform file (for example, `main.tf`).
47+
2. Configure it with your Fastly API token, Fingerprint proxy secret, integration domain, and other required values.
248

3-
* Copy your Fastly API token
4-
* Create your own terraform folder and create main.tf file
5-
* Fill the file like this:
649
```terraform
750
terraform {
851
required_version = ">=1.5"
952
}
1053
1154
module "fingerprint_fastly_vcl_integration" {
1255
source = "github.com/fingerprintjs/temp-fastly-vcl-terraform"
13-
fastly_api_token = "<your fastly api token>"
14-
integration_domain = "<your domain to serve fingerprint integration>"
15-
agent_script_download_path = "<random path like this: qwe123>"
16-
get_result_path = "<random path like this: asd987>"
17-
integration_path = "<random path like this: xyz456>"
18-
main_host = "<your origin domain to serve your website>"
19-
proxy_secret = "<your proxy secret>"
56+
fastly_api_token = "FASTLY_API_TOKEN"
57+
proxy_secret = "FINGERPRINT_PROXY_SECRET"
58+
integration_path = "INTEGRATION_PATH"
59+
agent_script_download_path = "AGENT_SCRIPT_DOWNLOAD_PATH"
60+
get_result_path = "GET_RESULT_PATH"
61+
integration_domain = "metrics.yourwebsite.com"
62+
main_host = "yourwebsite.com"
2063
}
2164
```
22-
* Run `terraform init`
2365

24-
# Deploy
66+
You can see the full list of the Terraform module's variables below:
2567

26-
Run these commands in order
27-
```shell
28-
terraform init
29-
terraform apply -target=module.fingerprint_fastly_vcl_integration.module.vcl_asset
30-
terraform apply
31-
```
68+
| Variable | Description | Required | Example |
69+
| ---------------------------- | --------------------------------------------------------- | -------- | ---------------------------------------------- |
70+
| `fastly_api_token` | Your Fastly API token | Required | `"ABC123...xyz"` |
71+
| `proxy_secret` | Your Fingerprint proxy secret | Required | `"9h7jk2s1"` |
72+
| `integration_path` | Path prefix for proxy requests | Required | `"kyfy7t0a"` |
73+
| `agent_script_download_path` | Path for serving the JavaScript agent | Required | `"cc7bu2o8"` |
74+
| `get_result_path` | Path for identification requests | Required | `"sy5k3279"` |
75+
| `integration_domain` | Domain used for the proxy integration | Required | `"metrics.yourwebsite.com"` |
76+
| `main_host` | Your origin server domain | Required | `"yourwebsite.com"` |
77+
| `dictionary_name` | Name of the Fastly Dictionary for config values | Optional | `"fingerprint_config"` |
78+
| `integration_name` | Name of the Fastly CDN service | Optional | `"fingerprint-fastly-vcl-proxy-integration"` |
79+
| `download_asset` | Whether to auto-download the latest VCL release | Optional | `true` |
80+
| `vcl_asset_name` | Custom VCL asset file if not downloading the official one | Optional | `"fingerprint-pro-fastly-vcl-integration.vcl"` |
81+
| `asset_version` | GitHub release version used for the VCL asset | Optional | `"latest"` |
3282

33-
# Custom VCL
83+
## 2. Deploy your Terraform changes
3484

35-
If you want to use your own asset instead of downloading latest follow these steps:
85+
1. Initialize the Terraform module:
86+
87+
```shell
88+
terraform init
89+
```
3690

37-
Place your custom asset in `<your_module_root>/assets/custom-asset.vcl` and then edit your `main.tf` file, and add these 2 variables inside "vcl" module block:
38-
```terraform
39-
download_asset = false
40-
vcl_asset_name = "custom-asset.vcl"
41-
```
91+
2. Apply the VCL asset:
4292

43-
Run these commands:
44-
```shell
45-
terraform init
46-
terraform apply
47-
```
93+
```shell
94+
terraform apply -target=module.fingerprint_fastly_vcl_integration.module.vcl_asset
95+
```
4896

49-
# Destroy
97+
3. Apply the changes to your Fastly service:
98+
99+
```shell
100+
terraform apply
101+
```
102+
103+
## Using a custom VCL asset (optional)
104+
105+
You can use your own VCL asset instead of downloading the official one:
106+
107+
1. Place your custom asset in `<your_module_root>/assets/custom-asset.vcl`
108+
2. In your `main.tf` file, add these 2 variables to the module configuration:
109+
110+
```diff
111+
module "fingerprint_fastly_vcl_integration" {
112+
# ...
113+
+ download_asset = false
114+
+ vcl_asset_name = "custom-asset.vcl"
115+
}
116+
```
117+
118+
3. Run `terraform init`.
119+
4. Run `terraform apply`.
120+
121+
## Examples
122+
123+
This repository also includes an example Terraform project. Use this example only as a reference, and make sure to follow best practices when provisioning Fastly services:
124+
125+
- [Minimal example](./examples/minimal/)
126+
127+
## How to update
128+
129+
The Terraform module does include any mechanism for automatic updates. To keep your integration up to date, please run `terraform apply` regularly.
130+
131+
## More resources
132+
133+
- [Documentation](https://dev.fingerprint.com/docs/fastly-vcl-proxy-integration)
134+
135+
## License
136+
137+
This project is licensed under the MIT license. See the [LICENSE](/LICENSE) file for more info.
50138

51-
To destroy, run this:
52-
```shell
53-
terraform destroy
54-
```

0 commit comments

Comments
 (0)