Gyms in Pokémon GO are real world locations, just like with PokéStops.
Gyms have two general states that can be seen by anyone close enough--They are either empty and unclaimed, or colored Blue, Yellow, or Red to represent the Team controlling it. In addition to color, the size of the Gym will scale on the map to represent its current level.
Trainers can't interact with Gyms until they reach Trainer level 5, after which they will be prompted to join one of the game's three teams. Once a player has chosen a team, they will be able to interact with a Pokemon Gym while it is within their interaction circle. If a Gym is empty, the Trainer may put a Pokémon of their own into the Gym and claim it for their team.
The Gyms' levels are based on the amount of Prestige they have, and can only hold one Pokémon for every level. If a Gym on a Trainer's team has a high enough level to hold more Pokémon than it currently holds, that Trainer may put one of their Pokémon into the Gym, assuming they don't already have one assigned there. The highest level for a Gym is 10, with a capacity for ten different Trainers' Pokémon.
If the Gym is owned by a Trainer's team, then they may train there by battling the Gym's Pokémon to increase the Gym's Prestige. The Pokémon are displayed and fought in order of lowest to highest CP scores with the Trainer's selected six Pokémon. Prestige is awarded as each defending Pokémon is beaten, with the amount of Prestige being based on the highest CP in the Trainer's party of six and the CP of the defeated Pokémon. The maximum amount of 1000 Prestige is awarded when a Pokémon is defeated using a party who's CPs are less than half that of the defender. The Pokémon with the highest CP assigned becomes the Gym Leader, and is displayed on the Gym's top. In addition to adding defense, each Pokémon added to a Gym awards it 2,000 Prestige for leveling. When a Pokémon is assigned to a Gym, the owner will not gain the use of the Pokémon or any customization of it until it is kicked out of the Gym. There is no other way to regain use of that Pokémon. Pokémon can also display a "Battles Won: X" number that shows how many times that specific Pokémon has stopped an attacker.
Trainers can attack rival Gyms to reduce that Gym's level. While attacking, a trainer can bring a party of six Pokémon with them that they can switch between freely. Pokémon defeated while attacking a rival Gym or training a friendly Gym faint, needing a Revive before they can be used again. After a Trainer wins battles against the Gym, its Prestige will be lowered. If this results in a loss of a level, the lowest slot for a Pokémon is removed. If a Pokémon is in that slot, then it faints and is returned to its Trainer. Once the Gym Leader is removed from the Gym, it becomes empty again and any team may claim it, however there is a short window in which only Trainers who defeated it may claim it.
Either with training or attacking, the Pokémon in a Gym will always start a battle at full hp, regardless of how much damage they have taken before.
How to battle
Currently, Pokémon Gyms are the only way to battle in Pokémon GO, although it is hoped that Trainers battling with each other will be implemented in a future update of the game. The mechanics to fighting in this game are different from any other Pokémon game, with three options during combat (other than retreating and switching Pokémon):
Swiping to the left or right will make your Pokémon move in that direction. When a Pokémon attacks you, a yellow burst will show on the screen. Immediately following the burst disappearing, you move to any side to avoid the attack. Currently, the burst and attack animations do not line up perfectly, so it is important to ignore the animations. In addition, there is a bug that causes your Pokémon to take a slight amount of damage occasionally even if you successfully dodge.
Basic Attack (Quick Attack)
Not the actual attack called Quick-Attack, but rather a Pokémon's basic attack. This is usually a simple, fast attack that still has a type. To perform this attack, tap directly on the screen. It may become mandatory in future patches to tap relatively close to the opposing Pokémon.
This is a slower attack that has a longer animation time, so it is important to time it when the opposing Pokémon isn't attacking frequently. It deals more damage than the basic attack, and can only be used when one of the boxes at the top of the screen is filled by performing basic attacks. It is performed by pressing and holding down on the screen for a short amount of time.
Trainers who have their Pokémon in a Gym get a reward other than glory for having control of a Gym. In the Shop, there is a button at the top right that displays a shield and a number inside of it. The number will display the amount of Pokémon you have defending Gyms, and can be tapped once every 21 hours to collect Pokécoins and Stardust. This is currently the only way to obtain Pokécoins other than purchasing them. You can control more gyms, but the maximum for collecting rewards is 10 gyms, which equals 5000 Stardust and 100 Coins.
Prestige required for Gym levels are shown below. Level 10 is the max level a gym can reach.