Using Visual Studio to edit your Home Assistant configuration.yaml file over SSH
Visual Studio Code is a powerful, but free, text editor provided by Microsoft. I find it to be the perfect solution for editing the various configuration files that you will come across when using Home Assistant or other home automation applications. The editor gives your powerful features like syntax highlighting and color coding, which makes it really easy to read complex configuration files and helps you spot when you've made any mistakes in formatting.
One of the most powerful features of Visual Studio code is the ability to add Extensions to it that enhance its functionality. One of these extensions is called the Remote - SSH extension and allows you to remotely connect to a computer via SSH to access and edit any text files that exist on the remote computer. It's super cool to be able to directly edit files on my home automation server from the comfort of my PC or laptop.
I use this setup to manage all of the configuration files running on my "Home Automation Server". It's an Intel NUC PC running Ubuntu Linux and Docker. I've written a blog post about my setup previously, so go check it out if you're interested.
In this post we're going to add this extension and configure it to access your linux server remotely over SSH. In order to follow along with this I will assume you already have the following:
A Windows or Mac computer that you can install Visual Studio on to
A Linux based home automation computer that you have SSH access to
Installing VSCode and adding Extensions
The first thing you will need to do is install VS Code. You can download it for free from the Visual Studio Code website. Once it's installed, open it up and you should see something like this.
Visual Studio Code editor
The first thing we want to do is install a couple of Extensions. To do this click the View menu and then click Extensions. You can also click the Extensions option in the left hand navigation bar.
At the top of the Extensions panel, you can now type in Remote - SSH and click Install under the correct extension.
Now repeat those steps to install the YAML extension, which will make it easier to work with the Home Assistant YAML files.
Congratulations! You now have Visual Studio Code installed!
Connecting to a remote computer from Visual Studio Code via SSH
Now that everything is set up, it's time to remotely connect to your Linux computer via SSH. Firstly, you should see a new Remote Explorer item in the left hand navigation menu. Click on it to open up the Remote Explorer panel and then click the Plus (+) button at the top to add a new target.
In the box that appears at the top type in ssh <username>@<ip address> where <username> is the user account you use when SSHing into the linux computer and <ip address> is the IP address of your linux computer. Then press Enter to continue.
Press Enter again to accept the default location to store this information in your user profile. This will mean you don't need to type this in each time you remotely connect to the server.
You should now see the new Remote Target added to the list. You should be able to now right click it and connect to it in the current window.
Select Linux as the platform
Click Continue to accept the key/fingerprint.
Then finally type your password in to connect to the remote computer. This is the SSH password associated with the user account you entered earlier.
It will now remotely install the VSCode extension on your linux computer and you should then be connected successfully.
Now that you're conencted to the computer via SSH you can open files and folders directly from that computer into your VSCode editor. If you followed along on my Install Docker and Home Assistant blog post then you know that I store all my container configuration files in my /opt directory. I find it most useful to open up this directory in my editor so I can just navigate around inside this folder to edit any of the configuration files that I need.
To open the /opt folder you can either click the File -> Open Folder menu option or click the Explorer icon at the top of the left hand navigation bar and the Open Folder button. Then type /opt into the folder text box and click OK.
You will now be prompted to enter your password again and it will load up that folder into your editor. You should now see all the files and folders in the /opt directory of your linux computer listed in the explorer panel - how cool is that?! Any time you add a new Docker Container with mappings to the /opt directory on your linux server, you will immediately see those files appear in this list.
You can now open any of these files and edit them within the editor. If you click Save it will save those changes directly onto your linux computer!
Commong Issues
There are a couple of issues I've seen from time to time.
File changes not taking affect
Remember that if you change your docker-compose.yaml file you will need to re-run the docker-compose up -d command from the /opt directory to re-create any containers that have been modified.
If you edit any of the Home Assistant YAML files, you will need to restart Home Assistant for the changes to be applied.
Permission Denied when saving files
You may experience a problem like this when trying to save files:
Failed to save: Unable to write file (NoPermissions (FileSystemError): Error: EACCES: permission denied)
To fix this I usually just give myself ownership permissions on the entire /opt/ directory. This is probably not the most secure option, but it worked for me and I've not seen any issues. Firstly, you need to SSH into the linux server as a user with root permissions.
Then run the following command where <username> is the username of the account that you are logging in to the server as from Visual Studio Code.
sudo chown <username> -R /opt