1 - Prerequisites
Codacy works by using Docker running in a containerized environment. This setup process will take around 20 min to complete, from an empty machine to a running Codacy installation.
To have this setup fully working, Codacy still needs to download its plugins (e.g.: its code analyzers) after it starts running. This process can take up to an extra hour, depending on network speed.
1.1 - Hardware
- 16 cores CPU
- 32GB RAM
- 1TB+ Hard Drive
Disk space use:
if your boot disk has very low capacity (something we often see on customers using sophisticated volume management):
- please mount /var/lib/docker on a volume with at least some 100GB free capacity just for Docker images;
- please mount the configured Codacy "Temporary folder" directory (which defaults to "/tmp") on your larger volume. This directory actually stores some application data.
- Do not mount directories under "/root", as Codacy will not be able to chown them to the appropriate user
Codacy basic service Docker images take around 15GB. but when Codacy starts operating it downloads all its analysers, which use a Docker based plugin system. After the analysers are downloaded you may have well over 20 GB of Docker images. We recommend a larger disk capacity to accommodate upgrades without frequent maintenance.
Extra considerations on CPU and RAM:
The default configuration is to run a maximum of 2 analysis in parallel, and our rule of thumb is to have 2 CPU and 4GB RAM extra per extra running analysis.
1.2 - Database
- PostgreSQL 9.4.x
Codacy requires a pre-installed PostgreSQL 9.4.x database, using a UTF-8 character set.
We recommend installing this database on a separate machine.
You can find setup instructions for this database here.
It is also possible to setup a local PostgreSQL 9.4.x database, but please note that the local database is recommended for testing purposes only. If you want to use a docker based database instance for this purpose (without data persistence between reboots), you can find setup instructions here.
You can test the connection from the Codacy server to the Database later on the setup process, just after you run the setup script the first time (which installs Docker) and before the second time (which installs the Codacy services). To test the DB connection, you can check if the Codacy server is able to successfully connect to it through PSQL running from a docker container:
1.3 - Software
We recommend installing Codacy on Ubuntu 16.04.
If you need to install Codacy on a different operating system please contact us first. Although docker aims at being environment independent, not all Linux distributions fully support the docker features that Codacy relies on to run. Installing Codacy on a different OS may yield unpredictable results or it may not run at all.
1.4 - Other target machine pre-requisites
Before installing Codacy:
- There should be no pre-installed Docker;
- There should be no user with id 2004;
- There should be no user group with id 2004.
User id 2004 and user group id 2004 are reserved for disk access privilege management, a drawback of running everything, code analyzers included, from Docker containers.
1.5 - Networking
1.5.1 - IP addresses and DNS
To ease maintenance, you should have a fixed IP address and/or DNS names for the Codacy server and the services it integrates with.
If you only have dynamic IP addresses for the above servers, integrations will break every time IP addresses change.
You should setup fixed IPs or DNS before installing Codacy, otherwise you will have to reconfigure and restart Codacy.
If you change the Codacy server DNS configuration, you will have to reboot it (or, at least, reboot Docker). This is caused by a limitation of the Docker service, which currently only picks up DNS configuration on start.
To check the DNS servers configured on your target machine, you can display its configuration file by executing this command:
In order to add a new DNS server to this configuration, use the nameserver command, as in:
1.5.2 - Ports to open for the Codacy server
For the target machine, before Codacy setup, make sure you have these ports open for inbound network traffic:
- 80 [TCP] - Application HTTP
- 443 [TCP] - Application HTTPS
- 9000 [TCP] - Control Panel HTTP
- 9443 [TCP] - Control Panel HTTPS
- 16005 [TCP] - Monitoring (average analysis times, analysis queues, ...)
- 16006 [TCP] - Application API (coverage, ...)
On the outbound traffic side, ensure that you can access the Internet from the Codacy server, including:
- getenterprise.codacy.com on ports 80 and 443 [TCP]
(download application setup and update packages)
- index.docker.io on port 443 [TCP]
(download application docker images)
1.5.3 - Database setup
Please make sure:
- you can access the PostgreSQL server you installed on its configured [TCP] port, 5432 by default.
- PostgreSQL is configured to accept connections from the Codacy server, as documented here.
1.5.4 - Access to servers you want to integrate with
Also ensure that:
- The Codacy server can access any services you want to integrate with (e.g.: Gitlab, e-mail) on their respective API / service ports;
- The services you want to integrate with (e.g.: Gitlab) can access the Codacy server.
(The ports that must be open on the Codacy server are already enumerated above.)
For a source code provider (e.g.: Gitlab, Github, Bitbucket) you must open whatever ports are used on the source code hosting for http, https, git and ssh protocols. Example:
- for GitHub, you are required to allow TCP ports 22, 80, 443, and 9418 for applications to function, as documented here.
2 - Installation
The installation is made with a one line shell script:
This script will update the kernel and install the required Docker version to run Codacy. If you previously installed docker, please check the documentation on how to uninstall it before running this script.
The script will need to restart the server to apply the changes. After the server restarts, run the same bash command as before:
The script will detect that docker is installed (it was installed with this script so you can ignore the warning) then ask for proxy configurations and whether a database should be installed. It will then proceed to install the Codacy Control Panel.
Using the provided Postgres will allow you to evaluate Codacy without having to properly install a Postgres database but, as stated in the Postgres installation guide, this database is not supported for production environments.
After this, you will be ready to start the configuration process in step (3).
3 - Configuration
The configuration interface is web-based and can be accessed via port 9000 over HTTP (e.g., http://192.168.0.1:9000) of the server you've installed on (make sure that the port 9000 is accessible from your local computer).
3.1 - Server license
The first screen will ask you for a license to be installed to access the application web UI. This will be a file with the extension .dlk. This will provide you access to download a custom built virtual infrastructure of Codacy that you can run in your own infrastructure.
3.2 - Control panel
After validating the license, you will be presented with the Codacy Control Panel, used to configure and update the application.
The console provides access to configuration keys and allows Codacy to be updated so it is strongly advised that the console is secured against unwanted access.
3.4 Application updates
For the initial application installation or future Codacy updates, click the button CHECK FOR UPDATES, on the top right corner. If a new update is available, a new option will appear:
Before any new version is ready to start running, a manual check of configurations is required. To configure the new version, click on the upper right corner link CONFIGURE. This will open a new screen with every configuration key required to run Codacy.
Codacy will run with the default settings, so if you are just evaluating the product with the default database there is no need to change anything; just click save.
If you want to configure an external database change following settings:
Host IP and Host Docker IP are automatically evaluated and secret keys to cipher database contents are created randomly per installation so no change is required.
After configuring the application, saving will return you to the update screen. This time, however, a new option to pull the version is presented in the upper left corner:
Pressing PULL will start an async method that can take up to 30 min, depending on your internet connection. This will pull Codacy images from dockerhub, making them available in the local registry for application execution.
When done, a success message will show in the logs, and refreshing the page will show a new option RUN in the upper right corner toolbar:
Pressing RUN will start the application. At any time, you can check the status of Codacy by navigating to Support:
There, all dockers will show their status. Also, the DOWNLOAD LOGS link will create a zip file with all container logs, that can be used to debug your installation at any time.
3.4.1 - Updating the Control Panel
Since the Control Panel version 1.0.60 (July 2016) the client can now update itself.
Some updates might require the latest version of the control panel. To download the latest version you need to login to the machine via SSH and execute:
bash -c "$(curl -fsSL https://getenterprise.codacy.com/get)" -s update
After the installation is completed you'll be able to access your server via HTTP on port 9000. There should be a new version running.
3.5 Running Codacy
If the database IP is incorrectly configured, Codacy will try to do an initial connection and wait on it before enabling the HTTP server. If the server is inaccessible, this will render Codacy unavailable.
You can navigate to port 80 (http) or port 443 (https) of your server in order to test your installation of Codacy. Codacy will provide you with a checkup page that will scan for any missed configuration setting.
Failed settings screen
When all settings are correct, Codacy will ask you to accept the License Agreement
After accepting it, you will be redirected to the initial registration screen.
The first user to register will be admin and will be able to administer the platform and create additional users.
3.7 Initial configuration
At this point, as the application finished downloading all components; internet access can be removed from the machine if required.
You should now go to 'Admin > Patterns' to select the default patterns. These defaults will be applied to new projects when registered into the platform.
Codacy is now ready to be used.
4.0 Additional configurations
HTTP - Custom Port
To change the default control panel port (9000) you should export the environment variable "DOPLICATED_CLIENT_PORT" before invoking the control panel update command.
bash -c "$(curl -fsSL https://getenterprise.codacy.com/get)" -s update
HTTPS - Control Panel
To have the control panel accessible with HTTPS, simply navigate to it and, in the settings panel, upload your CSR file without password, and the certificate key to the CSR file. By enabling the HTTPS settings, the control panel will be accessible through HTTPS, and it will use the configured port (9443 by default).
HTTPS - Codacy
To have Codacy accessible through HTTPS, click on "Configure" and set up the parameters as shown below; upload your CSR file without password, and the certificate key to the CSR file. This will enable HTTPS on Codacy on port 443 by default.
After this is complete make sure you "Save" and click "Reload".
HTTPS - Using HTTPS with an external load balancer
In case you rather setup HTTPS via an external load balancer (for example: AWS Load balancers), there are additional steps you need to take into account:
- Make sure the HTTP option is disabled in Codacy's Control Panel
- Ensure you have a redirect from HTTP to HTTPS
- Configure your git provider OAuth callback URL to use HTTP