The idea of having my own repository has lingered in my mind for a very long time. Three things stopped me from creating one earlier: (1) I thought all the required resources, server, and domain name would cost heaps of money, (2) I thought I needed to know how to code and be fluent in Terminal terminology, both of which I’m immune to learning, and

(3) I could not find a good unintimidating source of information that would explain to me (a total rookie) how to do it. But in the end I did it and the kr1sis Repository is running. The only thing that cost money was the domain name and server (they were, however, much cheaper than I expected). I did manage to modify a few codes, but I still don’t understand how much of it works (BUT it works and that is all that matters). I am now posting this tutorial which will explain from A to Z how I made my repo. And if I could do it, so can you! Just follow each step to the letter, download the files I give links to, and you will end up with your own Cydia repository.

UPDATE (30/4/2013): Almost a year after posting the original tutorial, I have finally updated it for Mountain Lion. Please let me know if you encounter any troubles.

Requirements (including my own specifications):

• Mac only (OSX Lion 10.8.3)
• xCode (v4.6.2) *
• Fink (v0.34.1) *
• XQuartz (v2.7.4) *
• DS_Store Cleaner (v1.6) *
• server with MySQL hosting (HostGator) *
• jailbroken iPhone
• iFile from BigBoss

* not a prerequisite as instructions on how to download / install / setup are provided within this post

Step 1 – Download & Install xCode / XQuartz

If you don’t have xCode already installed, you need to download it from here. Once installed, open xCode and go to Preferences. Select Downloads in the upper tab and install Command Line Tools.

Next download XQuartz from here. Install it.

Step 2 – Download & Install Fink

If you don’t have fink already installed, you need to download the file fink-0.34.7.tar from here and move it to your desktop. Extract its contents by double-clicking on it. Open the folder and click on a file called bootstrap. The terminal window will open and look like this:

By pressing RETURN you will choose the (recommended) option in brackets [ ] (in this case ‘Use sudo’). It will ask for your password which is your Mac user password. Continue pressing RETURN until it starts to download tarballs:

The downloading & setting up process might take a while (the downloads total just over 300Mb). Just continue pressing RETURN when prompted. Once the installation process is complete, close down Terminal and reopen it. Enter command:

This will set up your environment for Fink. Then enter command:

Enter password. More downloading & setting up occurs. I forgot to mention that you should probably find yourself a good book to read while you make your repo. Or you can go ahead and get started with steps 3 and 4. Once that is done, enter command:

Enter password. You are almost done. One last command:

More tarballs. But soon it will be all over and Fink is ready for action.

Step 3 – Setting up a server

If you don’t have your own server already set up, there are many hosting companies out there. Here is a link to the top ones (click on Read Review for more information about each one). They are all paid ($3.50 – $7.00 per month) but it is money well spend if you want a repository which is working more often than not. I first set up kr1sis Repository on a free server but moved it to HostGator within a month following too many frustrating days of being offline. You get what you paid for. If you do want to try it out on a free server first, here is a link to some free hosting companies available, but remember that moving a repo from one server to another is actually much easier said than done.

When choosing a server, make sure it provides PHP scripting and MySQL databases. This tutorial will explain how to upload all the necessary files and folders to your server using cPanel so choose a server that has it available. I believe all the servers listed in the links posted above meet all 3 criteria so it shouldn’t be a problem. Most of these servers require you to already have a registered domain name or provide you with a .com or .net one for a small fee. It you use or know of any other hosting company which you would like to recommend, please post it in the comments section below.

Once you register with a server, you should receive an email with all your information (usernames, passwords, nameservers, etc). Keep that email handy as you will require it to access your server (mine is printed out and stuck to the wall above my computer screen). Now log in and access your cPanel. Click on SUBDOMAINS to create the subdomain where your repo will be located (choose wisely as this will be the address of your repo in Cydia). I recommend you create repo.[yourdomainname]. If you are given this option, make the Document Root /repo.

Step 4 – Loading up your repo server

First of all, download this .zip file which contains all the folders & files that you will require to set up your repo as explained in this tutorial. Extract the contents and place the initialsetup.zip file and the repo folder on your desktop. Next, in cPanel click on FILE MANAGER. Open your repo.[domainname] subdomain’s root directory (usually /public_html/ by default, unless you have changed it to /repo/ as described in the previous step of this tutorial). Once you have open your root directory click on UPLOAD in the top bar menu. Then press the button CHOOSE FILE and select initialsetup.zip from your desktop. It should upload quickly. Once done, close the tab to return to the File Manager. You should be able to see the zipped file within the root directory. Now highlight initialsetup.zip by clicking on it once, and click EXTRACT in the top bar menu. Once extracted, your root directory should contain cgi-bin, depictions, and files folders, as well as the download.php, en_US.gz, index.html (or .php), and initialsetup.zip files. You can delete initialsetup.zip now – it has served its purpose.

The repo folder on your desktop will be a mirror image of your root directory online. It is helpful to keep it on your desktop to conveniently upload (and reupload) files to your server.

The last thing you need to do right now is to make your Cydia icon which will be the icon displayed next to your repo on the Sources page in Cydia. The Cydia icon needs to be a 64×64 px PNG file and saved as CydiaIcon.png (CaPiTaLiZaTiOn matters; this applies to this whole tutorial). Place it within the repo folder and upload it to your server root directory in the same way you did with the initialsetup.zip file.

Step 5 – Making your first package

I have built the basic structure of your first Cydia package. It is a folder called Repo-Icon within the _extras_ folder and will be a package that installs your Cydia section(s) repo icon(s). These are icon(s) for different Sections (e.g. tweaks, themes, etc) for packages hosted on your repo. Move the Repo-Icon folder to your desktop. If you open it you will see that it contains 2 folders: DEBIAN and Applications. As you will see, every Cydia package (or .deb file) in its uncompressed state is a folder containing a DEBIAN folder and “path to files” folder(s).

What do I mean by the “path to files” folder(s)? This is where iFile (the most useful app/tweak on a jailbroken iPhone) comes in. iFile operates like Finder on your Mac, giving you a way to navigate through all the files and folders on your iPhone. The “path to files” represents the path you have to take to get to the directory where you want the new files installed. In our case, we want to install the section repo icon(s) files in /Applications/Cydia.app/Sections/[here]. Therefore, the “path to files” will be an Application folder, within which will be a Cydia.app folder, within which will be a Sections folder, within which you will place your repo icon image file(s). Note that to open the Cydia.app folder you need to right-click on it and selecting Show Package Contents. The repo icon image needs to be a 64×64 px PNG file (you can use the same icon as for CydiaIcon.png) and saved as the name you decide to call your section. If the name of the section is longer than one word place an underscore in between words (e.g. My_Themes.png). Place it within the Sections folder. I decided to keep my repo simple (perhaps you might want to do the same) and all my packages are within the kr1sis Section, therefore my only repo icon image file is called kr1sis.png. In summary, the “path to files” for kr1sis.png will be /Applications/Cydia.app/Sections/kr1sis.png.

Other “path to files” you might find helpful include (but are not limited to):

BootLogos: /Library/BootLogos/[NameOfBootlogo]/…
Cydia apps: /Applications/[NameOfApplication].app/…
Ringtones: /Library/Ringtones/…
Wallpapers: /Library/Wallpaper/iPhone/…
Winterboard themes: /Library/Themes/[NameOfTheme].theme/…
Zeppelin logos: /Library/Zeppelin/[NameOfZeppelin]/…

The other folder in Repo-Icon is called DEBIAN. It contains a file called control. Let’s open the control file with TextEdit:

As you can see, it is a list with different properties of the package. Lets review them one by one as it is important that you do not make any mistakes.

Package: is the name of your package as Cydia will store it (e.g. com.kr1sis.repo-icon). Keep it simple, keep it lower case.

Name: is the name of your package as it will appear to other users in Cydia (e.g. Icon for kr1sis Repository).

Version: usually start with 1.0. If you update a package later, make sure the new version is higher that previous so it appears at the top of Changes in Cydia.

Architecture: always iphoneos-arm. DO NOT CHANGE.

Description: is the description of the package (e.g. This is a setup package for the kr1sis Repository).

Maintainer: is you or whoever owns the repo. Add your email between < > (e.g. kr1sis <me@kr1sis.net>).

Author: is whoever made the package. Again, add email between < > (e.g. kr1sis <me@kr1sis.net>).

Section: is the Section your package should be placed in (e.g. kr1sis; as discussed above, I only have one Section).

Priority: always extra standard (ignore the image above).

Depiction: is a link to a browsing window that will be inserted between the Author and Package Details parts on a package page in Cydia (e.g. http://repo.kr1sis.net/depictions/Repo-Icon.php). This is why package pages in different repositories (BigBoss, ModMyi, etc) look differently. I will describe to you later in this tutorial how to make depictions.

Installed-Size: is the size in bytes of the package when it is decompressed (e.g. 10377). It only takes the “path to files” folder(s) into account so the easiest method to determine the size is to right-click on the Applications folder, select Get Info, and bam! you got it. One last thing, but very IMPORTANT: after you type in the size, press RETURN and finish on a new line. Only then save your file as control (without any extensions such as .txt or .rtf).

Ok, so by now you should have a completed, uncompressed package in folder Repo-Icon on your desktop. It should have this “package tree” structure:

The next thing you need to do is clean your folder of .DS_Store files. What are they? They are invisible files that are created automatically within folders every time you open a folder with Finder. They contain information regarding each folder’s View Options. They are harmless but can interfere or corrupt a transfer or upload of packages between your server and Cydia. You can easily remove them with a Mac app called DS_Store Cleaner available for download here. Once installed, open it. You will see a pop up window with the text Drag Folders Here. Just do as it says with the Repo-Icon folder from your desktop, and…

You are now ready to compress your package. To do this open Terminal and enter the following two commands (press RETURN after each one):

 

If everything is well, following the second command you should receive an output message with 3 or 4 warnings, but the most important thing is that the file Repo-Icon.deb appears on your desktop. Congratulations, you have just made your first package. Move it into the files folder (inside your repo folder). It is probably a good idea to make yourself a folder where you will keep all the uncompressed packages (e.g. the Repo-Icon folder) so that in the future you can easily modify them if necessary. Alternatively, you can decompress a .deb file by entering the following command in Terminal (make sure the .deb file is on your desktop beforehand):

This will create 3 new files on your desktop: debian-binary (which you can immediately delete along with the original .deb file), control.tar.gz, and data.tar.gz. These last two files can be uncompressed by double-click. It will contain all the original files, however should you want to recompress them, you will need to rearrange them into the “package tree” structure (as described above) as well as DS_Store clean them beforehand.

You may want to include a package into your repository whose .deb file you have downloaded from a source outside of Cydia. You can place it directly into the files folder or uncompress and recompress them (don’t forget the DS_Store clean) if you want to modify its contents.

This might seem like a very lengthy process, but it has been so because you are only learning how to do it. With time, it will become quick and easy.

Step 6 – Preparing your Repository for Cydia

At this time, there should be only one folder on your desktop: repo. Clean up around it so you don’t make any mistakes (don’t hate me because I sound like your mother). What you need to do next is open your repo folder and place the Finder window somewhere in the corner so you can see what is happening within it. Then, open Terminal and enter the following commands:

You will receive a warning message but if you look carefully, a new file will appear inside your repo folder: Packages. Continue with the following commands:

Another new file will appear: Packages.bz2. Next command:

This transforms the Packages file into Packages.gz. Since we need the Packages file in the repo folder, we have to reenter the same command as before:

Next you need to open Release with TextEdit. Similarily to control, it is a list with different properties, but this time of the repository.

Origin: is the name of your repo as Cydia will display it in Sources (e.g. kr1sis Repository).

Label: same as Origin (e.g. kr1sis Repository).

Suite: always stable. DO NOT CHANGE.

Version: always 1.0. DO NOT CHANGE.

Codename: is the name of your repo as Cydia will register it. I suggested you make it the same as [yourcompany] in the control file (e.g. kr1sis).

Architecture: always iphoneos-arm. DO NOT CHANGE.

Components: always main. DO NOT CHANGE.

Description: this appears at the very bottom of your package page in Cydia (e.g. Email me if you have any questions or want to report a bug).

MD5Sum: is the fun part. It is a a 32-character long code that you need to generate for each of your Package, Package.gz, and Package.bz2 files. Go to http://www.hashemall.com to hash your files. Once the site opens first you need to choose the ALGORITHM MD5 and then press the button CHOOSE FILE. Select Packages in your repo folder.

Then click on HASH THIS FILE > and several seconds later (0.007 seconds is a slight exaggeration) you will be provided with a hash code:

Copy and paste the code onto the first column 32 asterisks in the row that ends with Packages. Next right-click on the Packages file within the repo folder and choose Get Info. Look at the size of the file (in bytes):

Copy and paste the size onto the second column 3 asterisks in the row that ends with Packages. Now repeat these steps for the Packages.gz and Packages.bz2 files. In the end, the Release file should look like this:

Save it. Now your repository is almost ready, just one last thing… Open Terminal and enter commands:

Then just type the following:

Type 3 then hit RETURN
Type 1024 then hit RETURN
Type 0 then hit RETURN
Type y then hit RETURN
Type your name then hit RETURN
Type your email then hit RETURN
Type the name of your repo then hit RETURN
Type o then hit RETURN
Type a good passphrase (I suggest you use the same as the password on your Mac) then hit RETURN. Repeat this as prompted.

This generates a key (what does it open? Please don’t ask me, I don’t know). Next you need to write the following commands:

Type your passphrase. You will notice the appearance of another file in the repo folder: Release.gpg. This time, you are officially done. All that you must do at this time is upload all your newly made files onto the corresponding folders on your server. At this stage your root directory should have the following structure (note that the cgi-bin folder and index.html file are often present when you set up your server account, do not delete or modify them):

Now the moment you have been waiting for… Open Cydia, go to Manage, open Sources, press on Edit, then Add, and enter [repo.domainname]. If all has been properly installed, Cydia will star downloading your package Repo-Icon and make it available in your repo. Give yourself a good pat on the back… You did it! If you open the Repo-Icon package page now, a large chunk of it will be missing since you haven’t yet made a depiction page. No worries though, I will now show you how to make them.

Step 7 – Adding Depictions to your Cydia package pages

I think the best way to show to you what is the difference between a Cydia package page with and without depiction is to show you a screenshot of both.

As you can see, depiction refers to the segment of the package page which can contain a banner, description tab, download counter tab, link to screenshots, and link to a URL. Cydia also adds a version tab and Filesystem contents tab (which is the exact “package tree” structure).

First make a banner image. It needs to be a 300px-wide PNG file. In order for it to look well aligned, add a transparent zone with a height of 17px above your image.

Save it as banner.png and place it within the images folder (inside the depictions folder).

Next you will need to make a depiction .php file for each package in your repo. In order to make such a file you first need to decide whether or not you want a link to screenshots to be displayed. If not, use xCode to open _Depiction.php from the _extras_ folder. If you do want a link to screenshots, open _Depiction_SS.php instead.

For now, modify the entries that are highlighted: (1) Description of App (the easiest way to do this is to copy and paste the Description line from the control file), (2) change [NameOfPackage].deb to the name of the .deb file associated with this depiction, (3) change [NameOfPackage].htm to the same as (2) but with .htm extension (notice that this line will be absent in the _Depiction.php file as there will not be any link to screenshots displayed), and (4) change [yourwebsiteURL] to a link to your website if you have one. Save the file as [NameOfPackage].php and place it inside the depictions folder. Make sure the name of the .php file corresponds exactly to the one in the Depiction line of the control file (for example Repo-Icon.php).

If you have chosen to link your depiction to screenshots (using _Depiction_SS.php as a template), then place your .png images inside the screenshots folder which is within the depictions folder. I recommend a width of 300px (and height of 450px if you want to preserve the iPhone screen proportions) for the images. Save them as [NameOfPackage]1.png, [NameOfPackage]2.png, etc. Then use Xcode to open _Screenshots.htm from your _extras_ folder.

Modify the entries that are highlighted: (1) App Name (I recommend to make it the same as in the Name line in the control file), and (2) change [NameOfPackage]1.png, [NameOfPackage]2.png, etc to the names of the screenshot image files. If there are less or more than 3 screenshot images, delete or add lines, but make sure that the last line finishes with a </div> instead of <br>. Save the file as [NameOfPackage].htm and place it inside the screenshots folder (within the depictions folder). Make sure the name of the .htm file corresponds exactly to the one modified in (3) in the _Depiction_SS.php file as explained above (e.g. Repo-Icon.htm).

Step 8 – Setting up the Cydia Package Download Counter

One of the last thing that I want to show you is how to make your package page show an download counter. First you need to open the cPanel on your server. Find and click MySQL DATABASES. Within MySQL Databases create a new database by writing a name (e.g. kr1sis_repodb) and pressing on CREATE DATABASE. Once you receive confirmation, press on GO BACK. Next add a new user by writing a name (e.g. kr1sis_user), generating a password (e.g. kr1sispassword), and pressing on CREATE USER. Go back. Finally add your user to your database by selecting a user and a database, and pressing on ADD. Go back.

Return to cPanel and find and click phpMyADMIN. Press once on your MySQL database’s name in the menu on the left side. Now press on IMPORT in the top bar menu. Press the CHOOSE FILE button and select the createtable.sql file which is within your _extras_ folder. Once your .sql file is uploaded, use Xcode to open the connect.php file:

Change yourusername, yourpassword, and yourdatabase to the username, password, and name of database that you just created (e.g. kr1sis_user, kr1sispassword, and kr1sis_repodb). Next, open the counter.php file, find out what is the time difference between your timezone and CST, and change ‘x’ (in both places) to that time difference (include ‘-’ if negative value; e.g. San Francisco: … NOW()+INTERVAL -2 HOUR …)

Now upload the modified files connect.php and counter.php as well as the htaccess file from the _extras_ folder to your root directory on your server. Once uploaded, highlight htaccess by clicking on it once, and click RENAME in the top bar menu. Change the name to .htaccess (i.e. add a ‘.’ in front of the name). The file may disappear from your root directory as files whose names start with a ‘.’ are hidden files (remember the .DS_Store files?)

You are now DONE! At this point you probably feel like your brain is totally overloaded and you start to wonder whether having a Cydia repository was worth all of this hassle. But do not despair. The hard part is over. From now on, all you have to do is add or update packages in your repository and I will summarise the process to you in the next step of the tutorial.

Credit: the original code for the download counter was written by damar1st. Please visit his website http://damarist.de.

Step 9 – Adding and Updating Packages in your Cydia Repository

Make sure the folder repo is on your desktop.

» ADDING AND UPDATING PACKAGE IN REPOSITORY «

1) If updating a previously created .deb file, place it on your desktop and uncompress it by opening Terminal:
|cd desktop
|ar -x [NameOfPackage].deb

2) Create New [NameOfPackage] folder on the desktop

3) Insert “path to files” folder(s) inside the [NameOfPackage] folder

4) Create New DEBIAN folder inside the [NameOfPackage] folder

5) Use _control file (inside the _extras_ folder) as template to make a new control file, or modify the one obtained by uncompressing the .deb file. Save it inside the DEBIAN folder

6) Clean .DS_Store files from the [NameOfPackage] folder with DS_Store Cleaner

7) Open Terminal:
|cd desktop
|dpkg -b [NameOfPackage]

8) Place [NameOfPackage].deb inside the files folder

» UPDATING REPOSITORY ON CYDIA «

9) Delete files Packages, Packages.gz, Packages.bz2, and Release.gpg

10) Open Terminal:
(|cd desktop)
|cd repo
|dpkg-scanpackages files / > Packages
|bzip2 -fks Packages
|gzip -f Packages
|dpkg-scanpackages files / > Packages

11) Update MD5Sums in the Release file (http://www.hashemall.com, remember to select MD5 algorithm)

12) Open Terminal:
(|cd desktop)
(|cd repo)
|gpg -abs -o Release.gpg Release
|passphrase = ‘??? should be same as Mac if you listened to my advice’

13) Use the _Depiction.php (no screenshots) or _Depiction_SS.php (with screenshots) file (both inside the _extras_ folder) as template to make a new [NameOfPackage].php file. Save it inside the depictions folder

14) If you chose to add screenshots, use the _Screenshots.htm file as template to make a new [NameOfPackage].htm file. Save it inside the screenshots folder. Add screenshot image files as [NameOfPackage]1.png, [NameOfPackage]2.png, etc to the same folder

15) Upload files to the root directory on your server (make sure to tick ‘Overwrite existing files’ before CHOOSE FILE): [NameOfPackage].deb, Packages, Packages.bz2, Packages.gz, Release, Release.gpg, [NameOfPackage].php, [NameOfPackage].htm, [NameOfPackage]1.png, [NameOfPackage]2.png, etc…

For your convenience, I have included a file copy of this summary inside the _extras_ folder (adding new deb.txt).

I hope this was helpful and you now own your very own Cydia repo. Please do not hesitate to contact me with feedback, comments, bug reports, or demands for further clarifications.

Step 10 – Little bonus :-)

Check out http://repo.[domainname]/download.php