Following on the blog Composer based deployment for PHP projects, in this blog entry we will explain in more detail on how to create a composer repository with Satis and a private GitHub repositories. We opted for this process as it suits our development workflow best. Since we are working on our local development server, and therefore we do not require a separate GitHub account for all users.
Requirements for your Server:
- Git, see installation guide
- Satis, see installation guide
- Composer, see installation guide
Other Requirements:
Free Account on GitHub
Create GitHub Repository and connect it to your local development:
- Login to GitHub with your account
- Create a new Repository
- Add repository name, make sure repository is private!
[image] - Confirm by clicking on Create Repository
Congratulations, now you have an empty repository on GitHub, let us fill it up! For that, we need to create a local Git repository on the server and connect it to the GitHub repository. In this example, we will use an existing not-Git project with some content in it. Important is that your project has to contain a composer.json which describes the project. Please refer to the official documentation.
Create local git repository:
- Connect to development server with SSH switch to your development user. I do not recommend using the root user of your system.
- cd to project folder, which you want to connect to your GitHub repository
cd ~/my-super-repository - Create a Git Project (Repository)
git init - Now add all the files inside this folder to the repository
git add - Create your first commit
git commit -m "Initial Commit" - Change the name of the 'master branch to 'main' in your local repository, as GitHub changed the name of the 'master’ Branch to 'main':
git branch -M main
If this went well, your local repository is ready to be connected. But as we created a private repository, this is the tricky part. Because we do not always want to log in to the repository when pushing something. There are a couple of ways to achieve this. I will use here the deploy key method.
Connect local repository:
- Create an SSH key pair, NOTE: we need to have a unique key per repository as GitHub does not allow us to use the same SSH key more than once. Therefor, we specify a unique filename for this key.
ssh-keygen -f ~/.ssh/id_rsa.GITHUB_MY_SUPER_REPOSITORY - Authorize the key in our GitHub repository by taking the following steps:
- Login to GitHub and navigate to your repository
- GoTo Settings > Deploy Keys and click Add deploy key
- Give it a title and copy the content of your public key
(cat ~/.ssh/id_rsa.GITHUB_MY_SUPER_REPOSITORY.pub)
Note: make sure that "Allow write access” is checked.[image]
- Tell the system to use this key when connecting to GitHub via SSH, defining it in the ~/.ssh/config (I'm using vim, but you can use any text editor)
vim ~/.ssh/config - Add the following content:
Host github-my-super-repository
HostName github.com
IdentityFile /home/dev/.ssh/id_rsa.GITHUB_MY_SUPER_REPOSITORY
For more information about the usage of this .ssh/config check out this link. Do a quick test to see if the setup is correct:
ssh git@github-my-super-repository
You know it is ok when the response is something like:
Hi RafaelYD/my-super-repository! You've successfully authenticated, but GitHub does not provide shell access.
Connection to github.com closed.Now you can connect to your local repository to the remote GitHub repository, by running the following command via SSH in your local Git repository:
git remote add origin git@github-my-super-repository:RafaelYD/my-super-repository.git
Note: As we are using git@github-my-super-repository, we do not need to worry about authentications. This is important for the setup of our composer Repository with Satis. Which is what we are going to do now. Don’t worry, the worst part is over. This next part is child's play!
Assuming that you have installed Satis via Composer as specified in the documentation. We will not go into detail here on how to set Satis up and all the features it offers. We will just look at an example on how to configure the satis.json for our Composer repository.
"As we are using git@github-my-super-repository, we do not need to worry about authentications."
Set up composer repository with Satis:
The satis.json for our example looks like this:
{
"name": "My Composer Repo",
"homepage": "https://myown-composer-repo.com",
"archive": {
"directory": "dist",
"absolute-directory" : "/absolute/path/to/satis/web/dist/",
"format": "zip"
},
"repositories":[{
"type":"vcs", "url":"git@github-my-super-repository:RafaelYD/my-super-repository.git"
},{
"type":"vcs", "url":"git@github-my-other-repository:RafaelYD/my-other-repository.git"
}],
"output-html": true,
"require-all": true
}
A quick overview of the most important parts:
Key | Description | Reasons / annotations |
Archive | Allows us to archive the content of our repositories in a predefined directory. In this case: The repositories will be zipped in the directory list with the absolute path /absolute/path/to/satis/web/dist/ | As a result, we always have a file on our server, and Satis will not depend on the connection to GitHub when a package is required |
Repositories | List of repositories where also our created repository is listed. Please see the documentation for details and supported types. For our purpose we use the type: vcs and in the url: git@github-my-super-repository so Satis can authenticate. | If your repository is not on the same server as your development, you will need to add a deploy-key for that server also. |
There you go! Now you will be able to deploy your project with Composer. You see that the first setup may be a little tricky. But once done, the fast deployment will pay for itself. And with GitHub and versioning control, you always have a backup. If necessary, you can easily roll back your changes.
You can read more about why, in the article Composer based deployment for PHP projects.
This article was written by Rafael our Full stack developer
