Introduction
Phinxer was created to address the limitations of existing web analytics solutions. Whether you are a privacy-conscious developer or an entrepreneur looking to cut costs, Phinxer provides a comprehensive, self-hosted solution. With a backend built on Express, a React frontend, and a robust data handling system utilizing Postgres and ClickHouse, Phinxer is designed to handle substantial traffic without compromising on performance or privacy.
This guide will walk you through the installation process, configuration options, and advanced usage scenarios, ensuring you get the most out of Phinxer.
Installation Instructions
Prerequisites
- Hardware: A server with at least 2GB of RAM and 2 CPU cores
- Operating System: Linux (Ubuntu 20.04 LTS or later recommended)
- Software: Node.js (v14.x or later), PostgreSQL, ClickHouse, Git
- Network: Properly configured firewall allowing traffic on necessary ports (80/443 for HTTP/HTTPS)
Step-by-Step Installation
-
Update and install dependencies:
sudo apt update && sudo apt upgradesudo apt install -y nodejs npm postgresql postgresql-contrib git
-
Install ClickHouse:
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv E0C56BD4sudo sh -c 'echo "deb https://repo.yandex.ru/clickhouse/deb/stable/ main/" > /etc/apt/sources.list.d/clickhouse.list'
sudo apt update
sudo apt install -y clickhouse-server clickhouse-client
sudo systemctl start clickhouse-server
sudo systemctl enable clickhouse-server
-
Clone the Phinxer repository:
git clone https://github.com/gnardini/analytics.gitcd analytics
-
Configure PostgreSQL:
sudo -i -u postgrespsql
CREATE DATABASE phinxer;
CREATE USER phinxer_user WITH ENCRYPTED PASSWORD 'yourpassword';
GRANT ALL PRIVILEGES ON DATABASE phinxer TO phinxer_user;
\q
exit
-
Configure environment variables:
Create a
.envfile in the root directory of the project with the following content:DATABASE_URL=postgres://phinxer_user:yourpassword@localhost:5432/phinxerCLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=9000
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=
SECRET_KEY=your_secret_key
-
Install Node.js dependencies:
npm install -
Run database migrations:
npm run migrate -
Start the Phinxer server:
npm start
Verification
To ensure Phinxer is running correctly, visit http://your-server-ip:3000 in your web browser. You should see the Phinxer dashboard.
Main Content Sections
Configuring Phinxer
After installation, configuring Phinxer to suit your specific needs is crucial. This includes setting up tracking scripts, customizing dashboards, and configuring alerts.
Tracking Script Integration
<script>
(function(d, w) {
w.phinxer = function() {
var n = d.createElement('script'); n.async = true; n.src = 'http://your-server-ip:3000/track.js';
var s = d.getElementsByTagName('script')[0]; s.parentNode.insertBefore(n, s);
};
phinxer();
})(document, window);
</script>
Insert this script into the header of your website to start tracking page views and events.
Customizing Dashboards
The Phinxer dashboard can be customized to display the most relevant metrics for your site. You can add, remove, and rearrange widgets to create a personalized view of your data.
Practical Examples or Case Studies
Example: Tracking User Engagement
Suppose you want to track user engagement on a particular page. You can set up event tracking within your Phinxer dashboard to measure actions like button clicks, form submissions, and more.
Advanced Configuration
For more complex scenarios, Phinxer allows you to set up custom event tracking, user segmentation, and detailed reporting. Refer to the official documentation for advanced configuration options.
Tips, Warnings, and Best Practices
Security Best Practices
- Ensure your Phinxer instance is secured with HTTPS by setting up an SSL certificate.
- Regularly update your server and Phinxer to the latest versions to mitigate security vulnerabilities.
- Use strong, unique passwords for your database and Phinxer admin accounts.
Performance Optimization
- Regularly monitor your server’s resource usage and scale up if necessary.
- Optimize your database performance by indexing frequently accessed tables.
Conclusion
Phinxer offers a powerful, privacy-focused alternative to traditional web analytics platforms. By following this guide, you can install and configure Phinxer to meet your specific needs, ensuring you gain valuable insights into your website’s performance without compromising on privacy or cost.
We encourage you to explore Phinxer’s advanced features and contribute to the project on GitHub.
Additional Resources
- Phinxer GitHub Repository – Source code and documentation
- Vike Documentation – Learn more about the Vike framework
- Express.js Documentation – Official documentation for Express.js
- React Documentation – Official documentation for React
- ClickHouse Documentation – Official documentation for ClickHouse
Frequently Asked Questions (FAQs)
What is Phinxer?
Phinxer is an open-source, self-hosted web analytics tool designed to provide privacy-focused analytics without the excessive tracking and cost associated with traditional analytics platforms.
Can I use Phinxer for high-traffic websites?
Yes, Phinxer is designed to handle substantial traffic efficiently. Its backend architecture leverages ClickHouse for event tracking, ensuring high performance.
How do I contribute to Phinxer?
You can contribute to Phinxer by submitting issues, feature requests, or pull requests on the GitHub repository.
Troubleshooting Guide
Common Installation Errors
If you encounter issues during installation, consult the following troubleshooting steps:
Error: “Database connection failed”
Ensure your Postgres and ClickHouse services are running and the credentials in your .env file are correct.
Error: “Phinxer dashboard not loading”
Check the server logs for any errors and ensure all dependencies are installed correctly. Verify that your firewall allows traffic on the necessary ports.
By following these steps and best practices, you can successfully leverage Phinxer for your web analytics needs. Should you encounter any issues, the Phinxer community and documentation are valuable resources for support and guidance.
