CONSUL DEMOCRACY installer for production environments
Using Ansible, it will install and configure the following:
- Ruby
- Rails
- Postgres
- Nginx
- Puma
- SMTP
- Memcached
- DelayedJobs
- HTTPS
- Capistrano
It will also create a deploy
user to install these libraries
How to setup CONSUL DEMOCRACY for a production environment
A remote server with one of the supported distributions:
- Ubuntu 20.04 x64
- Ubuntu 22.04 x64
- Ubuntu 24.04 x64
- Debian Bullseye x64
- Debian Bookworm x64
Access to a remote server via public ssh key without password.
The default user is deploy
but you can use any user with sudo privileges.
ssh root@remote-server-ip-address
Updated system package versions
sudo apt-get update
Python 3 installed in the remote server
The following commands must be executed in your local machine
Get the Ansible Playbook
git clone https://github.com/consuldemocracy/installer
cd installer
Create your local hosts
file
cp hosts.example hosts
Update your local hosts
file with the remote server's ip address
remote-server-ip-address (maintain other default options)
Run the ansible playbook
ansible-playbook -v consul.yml -i hosts
Note about old versions: if you've already used the installer before version 1.1 was released, you might need to remove your ~/.ansible
folder.
Visit remote-server-ip-address in your browser and you should see CONSUL DEMOCRACY running!
You can sign in to the application with the default admin user:
[email protected]
12345678
To restart the server and deploy new code to the server we have to configure Capistrano.
Create your fork
Setup locally for your development environment
Checkout the latest stable version:
git checkout origin/2.2.0 -b stable
Create your deploy-secrets.yml
cp config/deploy-secrets.yml.example config/deploy-secrets.yml
Update deploy-secrets.yml
with your server's info
production:
deploy_to: "/home/deploy/consul"
ssh_port: "22"
server1: "your_remote_ip_address"
user: "deploy"
Update your repo_url
in deploy.rb
set :repo_url, 'https://github.com/your_github_username/consuldemocracy.git'
Make a change in a view and push it your fork in Github
git add .
git commit -a -m "Add sample text to homepage"
git push origin stable
Deploy to production
branch=stable cap production deploy
You should now see that change at your remote server's ip address
Screencast update: The Installer now configures a queue to send emails asynchronously. Thus you will not see a 500 error when there is a misconfiguration, as the email is sent asyncronously and the error will be raised in the queue. To see email error logs open the rails console (cd /home/deploy/consul/current/ && bin/rails c -e production
) and search for the last error in the queue Delayed::Job.last.last_error
)
Update the following file in your production server:
/home/deploy/consul/shared/config/secrets.yml
You want to change this block of code for your production environment and use your own SMTP credentials:
mailer_delivery_method: "smtp"
smtp_settings:
:address: "smtp.example.com"
:port: "25"
:domain: "your_domain.com"
:user_name: "username"
:password: "password"
:authentication: "plain"
:enable_starttls_auto: true
And restart the server running this command from your local CONSUL DEMOCRACY installation (see Deploys with Capistrano for details).
cap production deploy:restart
Once you setup your domain, depending on your SMTP provider, you will have to do two things:
- Update the
server_name
with your domain in/home/deploy/consul/shared/config/secrets.yml
. - Update the
sender_email_address
from the admin section (remote-server-ip-address/admin/settings
)
If your SMTP provider uses an authentication other than plain
, check out the Rails docs on email configuration for the different authentation options.
To setup a staging server to try things out before deploying to a production server:
Update your local hosts
file with the staging server's ip address
remote-server-ip-address (maintain other default options)
And run the playbook with an extra var "env":
ansible-playbook -v consul.yml --extra-vars "env=staging" -i hosts
Visit remote-server-ip-address in your browser and you should now see CONSUL DEMOCRACY running in your staging server.
Using https instead of http is an important security configuration. Before you begin, you will need to either buy a domain or get access to the configuration of an existing domain. Next, you need to make sure you have an A Record in the DNS configuration of your domain, pointing to the correponding IP address of your server. You can check if your domain is correctly configured at this url https://dnschecker.org/, where you should see your IP address when searching for your domain name.
Once you have that setup we need to configure the Installer to use your domain in the application.
First, uncomment the domain
variable in the configuration file and update it with your domain name:
#domain: "your_domain.com"
Next, uncomment the letsencrypt_email
variable in the configuration file and update it with a valid email address:
#letsencrypt_email: "[email protected]"
Re-run the installer:
ansible-playbook -v consul.yml -i hosts
You should now be able to see the application running at https://your_domain.com in your browser.
These are the main configuration variables:
# Server Timezone
timezone: Europe/Madrid
# Authorized Hosts
ssh_public_key_path: "~/.ssh/id_rsa.pub"
ansible_ssh_private_key_file: "~/.ssh/id_rsa"
#Postgresql
database_name: "consul_production"
database_user: "deploy"
database_password: "change_me"
database_hostname: "localhost"
#SMTP
smtp_address: "smtp.example.com"
smtp_port: 25
smtp_domain: "your_domain.com"
smtp_user_name: "username"
smtp_password: "password"
smtp_authentication: "plain"
If you are on Ubuntu and would like to use its default sudo
group instead of wheel
, change the deploy_group
variable to:
deploy_group: sudo
There are many more variables available check them out here
The consul
playbook creates the database on the same server as the application code. If you are using a cloud host that offers managed databases (such as AWS RDS, Azure Databases, or Google Cloud SQL), we recommend using that instead.
To set up the application by itself:
- Fork this repository.
- Specify your database credentials (see the
database_*
group variables) in a vault. - Run the
app
playbook instead of theconsul
one against a clean server.
ansible-playbook -v app.yml -i hosts
Aside from just using managed databases, you might also look into platform-as-a-service options (like Azure App Service or Google App Engine) to not have to manage a server at all.
By default the installer assumes you can log in as root
. The root
user will only be used once to login and create a deploy
user. The deploy
user is the one that will actually install all libraries and is the user that must be used to login to the server to do maintenance tasks.
If you do not have root
access, you will need your system administrator to grant you sudo privileges for a deploy
user in the wheel
group without password. You will also need to change the variable ansible_user
to deploy
in your hosts
file.
Change the variable deploy_user to the username you would like to use.
http:https://docs.ansible.com/
Cross platform compatibility (Ubuntu, CentOS)
Greater diversity of interchangeable roles (nginx/apache, unicorn/puma/passenger, rvm/rbenv)
Code published under AFFERO GPL v3 (see LICENSE-AGPLv3.txt)