I got an error while installing Convox locally
Ensure you have followed the setup instructions for your local OS here. Memory requirements for running Docker/Kubernetes locally can often catch people out.
If you have an existing DNS service running on port 53 on your machine, that can conflict when trying to set up the local DNS resolution for your development Rack. Disabling the service during installation and forwarding traffic for
*.convox domains should help.
If you have a process running on port 80 or 443 on your machine, that can conflict when trying to set up the Load Balancer for your development Rack. Disabling the service or using a different port will fix the problem.
DNS issues with local rack on macOS
Check if DNS is set correctly with
scutil --dns, the output must show you an entry for
convox pointing to
% scutil --dns [...] resolver #8 domain : convox nameserver : 127.0.0.1 flags : Request A records, Request AAAA records reach : 0x00030002 (Reachable,Local Address,Directly Reachable Address)
In case you don’t see the entry for convox, configure the DNS here.
You can test if the DNS is working using the
dscacheutil package, the IP Address must be
% dscacheutil -q host -a name api.dev.convox name: api.dev.convox ip_address: 127.0.0.1
Make sure there is no other service using the port 53, 80 or 443 on your system, this may cause problems with the Convox API.
If everything is configure properly, try to flush your DNS resolver and access your rack again:
% sudo dscacheutil -flushcache % sudo killall -HUP mDNSResponder
Configure DNS with scutil on macOS
You can configure a DNS entry with scutil, it will create the entry in the resolver and you don’t need to create the
% sudo scutil > d.init > d.add ServerAddresses * 127.0.0.1 > d.add SupplementalMatchDomains * convox > set State:/Network/Service/convox/DNS > quit
sudo scutil command will open an interactive input,
d.init starts a new DNS entry,
d.add ServerAddresses set the IP address to be used,
d.add SupplementalMatchDomains set the domain to be matched,
set State:/Network/Service/convox/DNS set the entry name and
quit exit the scutil command. It will update the
/etc/resolv.conf and configure the all requests for
*.convox to be forwarded to the rack.
scutil --dns to check if the entry was created successfully.
I got an error while installing Convox in my cloud provider
The error message is usually quite informative. If you have existing resources running in your cloud provider and you are near your account limits, a Rack install can sometimes breach those limits, requiring you to request an increase in the appropriate resource (IP addresses, CPU allowances etc). Once your limit has been increased, the Rack should install successfully.
Sometimes the Cloud providers will have internal issues which can prevent certain actions. It’s always worth checking the status pages and reporting for your provider and retrying an install once the issue has been resolved.
A failed Rack install should either be able to continued with, or be uninstalled successfully as required. You can retry the installation by simply running
convox rack update -r <rackname>.
If your Rack consistently fails to install into your Cloud provider and there are no relevant issues reported then please raise a support ticket for us to investigate.
I get an error when I deploy my app to Convox
Sometimes the errors that come back from Kubernetes and/or the cloud providers are useful, sometimes they’re more obtuse.
You can check your Application logs with the
convox logs command. Use the
--since flags to help narrow down your output if needed!
You can view the logs from your App build process with
convox builds logs <build> if you are having issues at that stage.
Finally you can view the underlying Rack logs with
convox rack logs to look for information around scaling or other external events.
When you know there is an issue and want to stop a deployment, you can run the
convox apps cancel command. This will trigger an immediate rollback so you can fix the problem and try another deployment.
SSL Certificate Issues
Convox uses LetsEncrypt to automatically and seamlessly provision SSL certificates for your App’s domains if needed. In order for the provisioning to be successful, the DNS records for all the domains you list in your
convox.yml for your App must resolve to the router address for your Rack. If you get a certificate warning and see the certificate is listed as a “Kubernetes Ingress Controller Fake Certificate”, this means the provisioning has failed, most likely because of DNS resolution issues. Check these and try again!
Any Services within your App that expose a port will require a passing health check before receiving traffic. Deploying a Release of your App that does not pass the health checks will result in a rollback to the previous release. If this is your first release of a new App, a failing health check will result in a failed deployment. Failing health checks will be reported when promoting your Release:
Promoting RABCDEFGHIJ... 2020-02-15T21:16:50Z system/k8s/atom/app Status: Running => Pending 2020-02-15T21:16:53Z system/k8s/atom/app Status: Pending => Updating 2020-02-15T21:16:53Z system/k8s/web-56f5d77d7 Created pod: web-56f5d77d7-6gx8z 2020-02-15T21:16:53Z system/k8s/web Scaled up replica set web-56f5d77d7 to 1 2020-02-15T21:16:53Z system/k8s/web-56f5d77d7-6gx8z Successfully assigned abcde-myapp/web-56f5d77d7-6gx8z to gke-abcde-abcde-nodes-n1-highcpu-8-90530fd3-p77q 2020-02-15T21:16:54Z system/k8s/web-56f5d77d7-6gx8z Pulling image "gcr.io/abcde-123456/myapp:web.BABCDEFGHIJ" 2020-02-15T21:17:06Z system/k8s/web-56f5d77d7-6gx8z Successfully pulled image "gcr.io/abcde-123456/myapp:web.BABCDEFGHIJ" 2020-02-15T21:17:09Z system/k8s/web-56f5d77d7-6gx8z Started container main 2020-02-15T21:17:09Z system/k8s/web-56f5d77d7-6gx8z Created container main 2020-02-15T21:17:17Z system/k8s/web-56f5d77d7-6gx8z Readiness probe failed: HTTP probe failed with statuscode: 404
You should ensure that your App is able to respond to the health check probes to faciliate a successful deployment.
My app deployed but I cannot access it
convox services to find the load balancer endpoints for your application.
convox ps to determine if your application is booting successfully.
convox logs to inspect your application logs and cluster events for problems placing your container, starting your app, or registering with the load balancer.
My app stopped working and I want to restart it
You can perform a remote restart of an entire App (all running processes) from the CLI with:
$ convox restart -a app1
Or alternatively to just restart the
web service processes, you can perform:
$ convox services restart web -a app1
My CLI commands take a long time to return
If your local Kubernetes setup does not point to a valid cluster, that can slow down your Convox CLI operations as it tries to interrogate the invalid endpoint. In this case, you can set a local env var
$ export CONVOX_LOCAL=disable to stop the CLI from doing this and speed up your commands.
Still having trouble?
Some good places to search are:
- this site, via the search box on in the sidebar
- Community support is available on Stack Overflow.
If you still need help, feel free to: